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 good
battle 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.
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.
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.
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.
--
To UNSUBSCRIBE, email to [EMAIL PROTECTED]
with a subject of "unsubscribe". Trouble? Contact [EMAIL PROTECTED]
