Re: [Stratagus-devel] documentation

[Gary Frederick]

Thanks Martin,

more below.

Martin Renold wrote:

> 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?

The class is only 10 weeks long. The kids are just starting, some are 12 
years old and the rest are not much older. I may do the class again in 
the spring and I may have some of the kids keep working on things after 
this class is over. It depends on what they want to do...

> 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.

I was planning on using Freecraft as one of the games in the class. I 
was about ready to start and then read about the Cease and Desist. darn

I would like to have a real simple demogame that the kids could use to 
learn. They want to add a new race. I told them we may want to hold off 
till we know a bit more :-)

Good documentation built around a demogame may be a good teaching tool 
for me. And shoud be useful to the community.

> 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

I will teach them about tools next week. CVS, debugers, IDEs... They 
probably need some experience before they get commit privs. :-)

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

I have never used a Wiki (no special reason, just happened that way) so 
if someone else wants to set one up, I will see if the kids want to use 
it. I'm happy with the tools the GNU folks provide.

> 5) other ideas?
>
> bye,
> Martin

I'll continue to work with my class and see what we can do to help.

Thanks,

Gary
  garyfreder on IRC