Roberto C. Sanchez wrote:
On Tue, Feb 06, 2007 at 06:19:00PM -0500, Michael Pobega wrote:Sounds like exactly what I had in mind, and seems like a pretty goodbattle plan for jumping into the documentation. What format will the document be written in initially, plain text? I figure if we do plain text initially (with a .html extension for word wrapping) we could easily mold that into any other format.I hate to use buzzwords, but this might fit with well with something like XML (or probably SGML), since it is easy to create transforms into different formats. The same source can be used to generate plain text, HTML, PDF and so on.
This is how NewbieDOC articles used to be produced. They were written in SGML, using a Docbook DTD, and then rendered into HTML and PDF using jade and sgmltools-lite. There is an article that explains how this worked at http://newbiedoc.sourceforge.net/metadoc/docbook-guide.html.en.
Articles were developed in CVS with help and suggestions via a mailing list. When the article was finished, the webmaster added it to the website.
This was too complex for really new newbies. Even today, the easiest way to edit SGML/XML is to use Emacs or Vim with the appropriate mode/plugin. It is much easier to produce Docbook SGML or Docbook XML using LyX (the WYSIWYM editor), but this aspect of LyX is not well-developed. Getting to grips with using CVS is also quite a hurdle for non-techie newbies. NewbieDOC now uses the wiki approach. Anyone can write anything immediately to the wiki. It could even be just plain text. The built-in editor contains buttons for basic formatting so you don't even have to learn the formatting syntax.
Osamu Aoki edits the Debian Reference etc. This is another possible model for Doug's ideas. There are many contributors but the editor produces the final document.You might want to check how the current Debian documentation is done. I know that they maintain it in some sort of CVS or Subversion repo which is accessible online. There are also packages in Debian to ease this sort of thing.
A mixed system might work well. Individuals produce small articles on specific topics. An editor uses these as source material for a major article. The major article would then have a consistent flavour, but contributors still retain "ownership" of their own artcles. Contributors would be able to continue to maintain and develop their own articles. This would help in process of revising the major document.
-- Chris.