[Nitro] Nitro Documentation Project (NDP)

Michael Kohl citizen428 at gentoo.org
Fri Sep 2 08:10:00 EDT 2005


Ok, I've been thinking about this since subscribed to this list,
because quite a lot of mails deal with the perceived lack of
documentation.

That's why I propose the formation of a Nitro Documentation Project
(NDP) *in the community*, so George and the other people can focus on
writing Nitro instead on writing docs. This doesn't mean that the NDP
won't work closely with them though.

So, what is this thread for?
----------------------------

1. To get a feeling how many people would be interested in
participating in this project. The good thing on writing docs is that
nearly everyone can help by e.g. proof reading, translations etc. Even
people with heavy time constraints can usually find some minutes/week
to proof read some stuff or write a sentence here or there.

2. Define what exactly is needed. Looking at Rails (although the
constant comparison of Nitro and Rails starts to get annonying after a
while, I know) might give us some hints:

http://documentation.rubyonrails.com/

3. Define priorities. Sure, every doc is valuable. Nonetheless some are
more needed than others. For example the vides Rails provides are nice,
but I'm sure most people will agree that what Peter mentioned earlier
("Real documentation would have a bunch of best practices for all
common tasks, as well as listings of all the tools you have in
different contexts.") would be more important for the time being.

4. Define which format to use. Wikis are undoubtedly nice, but we
should at lest consider alternatives. E.g. Gentoo's documenation is
written in GuideXML (http://www.gentoo.org/doc/en/xml-guide.xml), which
then gets converted to HTML via xslt. That's pretty neat, as it allows
us to generate different output from the same source easily. This may
or may not be intersting for Nitro, but at least we should discuss it.

5. Misc stuff. E.g. could we get a subdomain like
http://documentation.nitrohq.com? Would it make sense to create a
separate ML called nitro-docs for the coordination of the docs team?
Everything else that comes to mind.

Why should you participate?
---------------------------

1. This is free software. You perceive a problem. Fix it!
2. You help yourself and others. 
3. You help Nitro, which is a nice way to say "thank you!" to George
and the others.

I for one definitely am willing to participate in such a project,
although I'm currently low on time (I'm currently writing my diploma
thesis and Gentoo absorbs quite a lot of my time too). Nonetheless I
think I will be able to spend an hour or two per week on this, and if
e.g. 4 other people join this effort, we'd have between 5 and 10 hours
a week dedicated to Nitro documentation, which is not that bad.

Sorry that this mail got so long, but if you're reading this sentence,
you're obviously interested in this project, so do the right thing and
volunteer! "Uncle George needs YOU!" ;)

Cheers,
Michael

-- 
web at citizen428.net                                 citizen428 at gentoo.org
http://citizen428.net/                http://dev.gentoo.org/~citizen428/
GnuPG key: 0x90CA09E3/4D21 916E DBCE 72B8 CDC5  BD87 DE2D 91A2 90CA 09E3



More information about the Nitro-general mailing list