(Illustration by Gaich Muramatsu)
Thank you for the feedback and many suggestions regarding documentation. Based on this input, here is how we have decided to proceed: 1. Highest priority is accurate man pages. We will stop using docbook. It made the build depend on a whole suite of parsers and stylesheets that weren't necessarily installed when people tried to build Coda from sources. And all the docbook2man parsers still required additional tweaking ('-' -> '\-', etc.) Instead we will simply use native nroff, which can be used without problems on any system that does Unix manpages, and there are several programs to convert them to readable HTML if we ever want that. Editing is also somewhat easier since there is a pretty usable open source tool for editing man pages (http://wolfpack.twu.net/ManEdit/). A soon-to-be-released Coda-6.0.9 will have all the man pages in nroff format, but they may not be accurate yet. Our goal is to make them accurate by a soon-to-follow Coda-6.0.10 release. 2. Next priority is "official" manual. We will separate the current manual into an internals manual and a system administrator's manual. The system administrator's manual is higher priority; internals manual (including things like RPC2, LWP, etc.) will follow. The "official" versions of both manuals will be released as HTML (both on-line browsable and as a tarball) along with a PDF or PS version on our website, where the on-line version has the ability to add user comments at the bottom of each page (that Jan explored with some of you on codalist). The community can contribute by adding comments if they notice unclear descriptions and missing or outdated information in the manual. From time to time, we'll merge the comments into the next release of the "official" manual. 3. The wiki will be a place where the community can freely add useful pieces of information about Coda. We can't promise that the information on the wiki is correct, as we are not going to be able to track or correct those changes. The kinds of information that are already in the Wiki (e.g. performance measurements, useful tips on installation, optimization, etc.) are perfect for Wiki format. But we'll keep the official manual out of the wiki, as discussed in (2) above. 4. Lowest priority are tutorials, howto's etc. These are probably best done as contributions by the community. The most likely path here is that such documents would be constructed on the Wiki and at some point once they have been refined and checked for accuracy we could put a 'blessed' version on the Coda website in both HTML and PDF format. Please speak up soon if you see any serious problem with the above plan. Otherwise, we hope to get started on these changes soon. Help from volunteers in the cleanup will be gratefully accepted! -- SatyaReceived on 2005-04-26 21:58:21