Re: [Stratagus-devel] documentation

[Martin Renold]

On Thu, Oct 09, 2003 at 11:53:28AM -0500, Gary Frederick wrote:
> I'm holding a class for some kids and one of the projects they may do 
> may result in some documentation for Stratagus. Is there a documentation 
> group for Stratagus? Plans for more documentation we should look at?

Current documentation status:

http://www.nongnu.org/stratagus/documentation.html
contains some individual issues plus a link to the documentation
generated from the sourcecode comments. 

The main documentation for making games is the ccl documentation that
comes with the engine (FIXME: put it online) in the doc/ccl/ directory.
It is proabably still incomplete and some parts are not really useful or
outdated.

There is some more docu scattered in the doc/ directory, but IMO not very
useful and parts of it are describing W*rcr*ft specific issues (eg
doc/media.html describes the passenger animation but does not even
mention that there are animation scripts; it should link to them)

And then there are the W*rcr*ft ccl (FIXME: which come still with the
engine), they contain comments which should be moved to doc/ccl/ instead.

And there is demogame, which is the same as aleona (which is still the
same as FCMP which is W*rcr*ft with free media) except that I recently
removed most units from the mythical race to make look a bit simpler.

And one last thing, since the ccl syntax changes fast recently there is a
seperate mailinglist "stratagus-ccl" (FIXME: link it on the contact page)
where changes are announced.

OK, so what could be done?

a) what I think is missing most is some sort of "how to make a game with
stratagus" tutorial, which shows you and links to the relevant ccl
commands and other docu in order, explains the palette restrictions,
etc...

b) update doc/ccl/, add missing features (look up examples and misplaced
documentation in the ccls), actually try to change things and write down
what was hard to discover

c) add introductions to the modules (more useful than "Everything around
the $FILENAME", eg describe the pitfalls and link the most often used
commands)

d) give some structure to doc/*.html, update stale things, link
everywhere to the ccl commands mentioned

OK, but how could it be done?

1) Start a new homepage, and don't change what is already there.

2) Take what is there, change it, and send it back to a developer who can
commit it. You should merge often (since the effort is not visible to
other documenters, and there might be changes in the meantime). The
developer might get annoyed, by the way, if you don't know what a
"unified diff" is ;-)

3) become stratagus developers with cvs access and commit changes
directly

4) Move the documentation into a Wiki (a world-writeable html page, see
http://www.wikipedia.org/ for a prominent example)

5) other ideas?

bye,
Martin