"Tommy Killander" wrote: >> -----Original Message----- >> From: [EMAIL PROTECTED] >> [mailto:[EMAIL PROTECTED] Behalf Of Eduardo >> Roldan >> Sent: den 25 juni 2003 19:02 >> To: [EMAIL PROTECTED] >> Subject: Re: [Freevo-users] Re: Documentation (again) >> >> >> I like the wiki and the idea of a real document. >> >> See the php manual at: http://www.php.net/manual/en/ >> I think that freevo needs that type of 'knowledge base'. Standard >> documentation updated not so regularly with the posibility that users >> add coments in any place. When the comments grow up the documentation >> editor push them to the standard documentation and deletes the outdated >> ones. In this way developers can dump his ideas, users his experiences & >> frustrations. >> > > I agree.
Me, too > In order to make the information both valid and possible to find I believe > that a well structured Wiki should be possible to use for user comments, > hints and experiences. > I also believe that a snapshot of the Wiki user documentation should be > moderated and packaged together with each stable release (as a bundle of > HTML-docs or PDF). > > Documentation should be labeled and released using the same baselines as the > binary releases. The documentation for freevo-1.3.2-pre5 should be valid for > that release - not containing outdated stuff from freevo-1.3.1 or untested > stuff targeted for freevo-1.3.3-pre1 :-) Again agreed: if the docs are in the Freevo package, you will always have the right doc for you. > - Users Guide (end-user documentation). How Freevo operates from the users > point of view (could be a HTML, PDF or why not an embedded documentation > system in Freevo itself!?). I would prefer docbook. It's easy to write (take a look at Docs/freevo_howto.sgml) and you can tranform it into html, txt and pdf. > - Installation Guide. Something like a HOWTO. What do I need, how do I get > this bugger up and running. FAQs, Hardware/Software compatibility guide. > Some basic info on the system architecture and minor customisations of > Freevo. All definitions in "freevo_config.py" should be documented here! We have a start for that (again: Docs/freevo_howto.sgml). The problem is that we developer like to code, not to document. What I would like to have: Some people (two or three) working on the docs. They convert the stuff from the WiKi into the document. The WiKi itself will be for small tips, hardware ideas and stuff like that. Users could add some doc to the WiKi, the doc writers move that into the real doc. They also read the devel list to be up-to-date. If a developer creates something new, he sends a small description to the doc maintainer and they add it. > - Design Documentation. Code Style Guide, Software structure, API > documentation. TODO lists. There shouldn't be millions of pages of > documentation - but there should be enough to make sure that developers and > contributors are aligned in terms som code style, use of objects and APIs. > Properly designed code is easier to integrate in the existing software and > contains less bugs... > I think that the documentation found at http://www.directfb.org/ is good. > Look at the Overview document > http://www.directfb.org/documentation/DirectFB_overview_V0.1.pdf for an > example of high level documentation to give newcomers an introduction on how > the pieces fits together. That look like something one of the developers should do. A task for me would be to explain the plugin, menu and event system for plugin developer. >> I'am alone? No -- A bad random number generator: 1, 1, 1, 1, 1, 4.33e+67, 1, 1, 1... ------------------------------------------------------- This SF.Net email is sponsored by: INetU Attention Web Developers & Consultants: Become An INetU Hosting Partner. Refer Dedicated Servers. We Manage Them. You Get 10% Monthly Commission! INetU Dedicated Managed Hosting http://www.inetu.net/partner/index.php _______________________________________________ Freevo-users mailing list [EMAIL PROTECTED] https://lists.sourceforge.net/lists/listinfo/freevo-users
