On 3/27/13 11:35 PM, rob_hirschf...@dell.com wrote: > 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). Yes, I agree. In general I have no problems with the framework. > There are some framework gaps (like PDF output) that can be addressed as we > progress. Yes, it should be relatively easy to export pdf's if someone spends a bit of time to do it right. > Are you OK w/ the framework? Yes, the framework seems decent although I would argue that markdown is not really the best format to write documentation but at least for now it seems to work. I am sure we will notice if it becomes a problem.
One thing to note: susestudio uses an extremely similar framework which is available as a ruby gem. Maybe a developer would like to look into that and see if it would be a better alternative? Better in the sense that it works as well and there would be less maintenance from this group :-) -- Kenneth Wimer > > 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 > -- 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/
