All excellent points. I think that we need to distinguish between the framework and the content for discussion.
To me, your comments are about content gaps (which are significant). There are some framework gaps (like PDF output) that can be addressed as we progress. Are you OK w/ the framework? Rob -----Original Message----- From: Kenneth Wimer [mailto:wi...@suse.de] Sent: Wednesday, March 27, 2013 5:12 PM To: Hirschfeld, Rob Cc: ja...@suse.de; crowbar Subject: Re: [Crowbar] System Documentation UI On 3/27/13 10:27 PM, rob_hirschf...@dell.com wrote: > No - I'm saying to embed them. Let me explain. Right, this is what I understood. > > We've created a system that consolidates all the docs into a consistent place > and breaks them into manageable parts. We're maintaining all of the docs in > that way. That seems like a very good thing to me. I would argue how manageable they are (much more so in development mode). They are manageable in a directory listing kinda way but not in an informational sense. I have nothing against including the development docs on the same manner and only displaying them when in development mode but we definitely need to add some UI work to it (more on this below). Also, I think that the idea of separating the docs into distinct user oriented groups/books is the right way to go. Currently the information seems well spread over a large number of pages in an incoherent manner. The info itself is for the most part very good but trying to find specific information by the group/section naming and page naming is very hard. > We've create a way to export all of the docs into single books to be used > outside of the UI and github. That seems like a very good thing to me. We still need to work on the structure and markup of every book but I completely agree with this. The current implementation only allows you to "export" the current page and the "export" function is really just a css switch to make the page more printable. I would argue that we need to take step further and offer the entire book as PDF download instead of the current system. > We've got a way to link content sections back to github so readers can easily > find where to make corrections. That also seems like a good thing. The current system of showing a long string with the source of the page is distracting. I see the point of showing the source but we should probably think of another way of displaying this information in a way that is informational but not so visually distracting. Also, some explanation and details for contribution, style and structure would be needed. > Since we've got all the content in the UI, I don't see why we should omit a > link to it. Filtering it out is more effort. I agree that in development mode there can/should be links to the developer docs. Other things to think about would be a simple style guide to keep the various pages in-line as to numbering, etc. Having looked through all the docs I think they all need a lot of work improving markup and structure and I wonder how we can improve them all in a consistent manner. -- Kenneth Wimer > > -----Original Message----- > From: Kenneth Wimer [mailto:wi...@suse.de] > Sent: Wednesday, March 27, 2013 1:58 PM > To: Hirschfeld, Rob > Cc: ja...@suse.de; crowbar > Subject: Re: [Crowbar] System Documentation UI > > On 3/27/13 7:29 PM, rob_hirschf...@dell.com wrote: >> +1 >> >> Where would you see the developer docs link? > Typically, I would expect the developer docs to be on the wiki in github. I > have nothing against showing them in the System Documentation in development > mode but a) it seems like the last place I would look for such information > and b) when the crowbar ui is broken (and therefor needs development) the > docs are also down. > > To reiterate, I would leave the user-based docs in the git repo > directly and put the developer docs on the github wiki. Just my two > cents :-) > > -- > Kenneth Wimer > >> -----Original Message----- >> From: crowbar-bounces On Behalf Of Kenneth Wimer >> Sent: Wednesday, March 27, 2013 10:49 AM >> To: James Tan >> Cc: crowbar >> Subject: Re: [Crowbar] System Documentation UI >> >> On 3/27/13 3:49 PM, James Tan wrote: >>> On 03/27/2013 03:02 PM, Kenneth Wimer wrote: >>>> I noticed the typos already and fixed them in the SVG file. BTW, I >>>> made all of this with inkscape so if someone is interested in the >>>> source files I'll put them in the repo as well. >>> Sweet. Yes why not just push the .svg in - I think most modern >>> browsers can render that directly? >> Most browsers can do svg but not inkscape svg. I have each wireframe on a >> different layer and the notes for each again on a different layer. I imagine >> it will look pretty messed up in a browser. >> >> I am about to push the corrections to the images and the source svg. >> >> -- >> Kenneth Wimer >> >> SUSE LINUX Products GmbH, GF: Jeff Hawn, Jennifer Guild, Felix >> Imendörffer, HRB 16746 (AG Nürnberg) Maxfeldstraße 5, 90409 Nürnberg, >> Germany >> >> _______________________________________________ >> Crowbar mailing list >> Crowbar@dell.com >> https://lists.us.dell.com/mailman/listinfo/crowbar >> For more information: http://crowbar.github.com/ > > -- > Kenneth Wimer > > SUSE LINUX Products GmbH, GF: Jeff Hawn, Jennifer Guild, Felix > Imendörffer, HRB 16746 (AG Nürnberg) Maxfeldstraße 5, 90409 Nürnberg, > Germany > -- Kenneth Wimer SUSE LINUX Products GmbH, GF: Jeff Hawn, Jennifer Guild, Felix Imendörffer, HRB 16746 (AG Nürnberg) Maxfeldstraße 5, 90409 Nürnberg, Germany _______________________________________________ Crowbar mailing list Crowbar@dell.com https://lists.us.dell.com/mailman/listinfo/crowbar For more information: http://crowbar.github.com/
