On 7/29/07, David Chisnall <[EMAIL PROTECTED]> wrote: > On 29 Jul 2007, at 18:05, Yen-Ju Chen wrote: > > > I think we should start to write some user documentation > > considering we have several applications already. > > I agree. This should be a big priority for 0.3. > > > Unlike frameworks, it is impossible to generate such documentation > > from source code. > > Randomly thinking aloud, I wonder if you could embed the information > in a nib in the same way you embed comments in source files for gsdoc.
I don't think nib has anything like that. And one thing I don't like for user documentation is to list all the menu items and UI. It is not very useful for users to start with. I like user documentation to start with introduction and some common tasks, then put all the details in the end as reference. The Cairo API documenetation is what I have in mind (incomplete): http://www.cairographics.org/manual/ It gives a tutorial first, then details as reference. So you only need to read the first 3-5 pages to start using the applications, and go back to find out more details if you want. > > > So we probably need to write the documentation by hand. > > We also need to decide which syntax/tag system to use > > and put the html'd version on web site. > > In such case, I think we can use etoile's gna web page > > (http://home.gna.org/etoile/) > > so that all modification can be tracked. > > Good idea. We ought to use that space for something. I wonder if we > can put API docs in there easily too. I propose we can map the current directory structure as web page. So if source code of StepChat is at stable/Etoile/Services/User/Jabber and the document is at web/Etoile/Sercies/User/Jabber For frameworks, the documentation will be their API. The first page for each component is probably 'index.html' We also need to have a defined file structure which can be refered from other components. For example, account setting in StepChat may need to refer to a session of AddressManager document. Having a fixed file structure will make less broken links. > > > Any suggestion for the syntax system (plain html, docbook, ReSt, > > etc) ? > > To reduce the overhead of having tool, I personally prefer plain HTML > > with some CSS. > > I think there are suffficient tools out there to convert them into > > PDF. > > That's pretty much all we need for user documentation. > > I'd like something that the help viewer can read, and that is easily > searchable. RTF seems to be standard for GNUstep, but is no fun to > work with. I'd prefer HTML + CSS if we can get SimpleWebKit working > (if not, there's an experimental XHTML-IM parser in TRXML that could > possibly be used). Yeah... I am considering to have a very simple one for NewsStand. I don't think SimpleWebKit is going to support CSS any time soon. It is very complicated. Yen-Ju > > David > > _______________________________________________ > Etoile-discuss mailing list > [email protected] > https://mail.gna.org/listinfo/etoile-discuss > _______________________________________________ Etoile-discuss mailing list [email protected] https://mail.gna.org/listinfo/etoile-discuss
