[Scummvm-devel] Documentation

[Henry Bush]

Hello guys,

I'm concerned about the documentation: it is quite a mission to update
it. I'm not talking about getting good documentation ready now (i.e.
ready for a 1.0 release), that's fine, it's just gonna take time. I
mean in order to keep it current in the future (i.e. after a 1.0
release ;-). At the moment there are at least three different places
where any major change in the ScummVM system would have to be added /
changed:

1) The manual in the wiki
2) The docbook manual
3) The README

Now you can say that it would be easy to use awk / perl or whatever to
convert one to the others, this would be ideal, but it strikes me that
it's not quite as simple as that (do correct me if I'm wrong). For
example, in the README we have a list of supported games: this is not
present in the wiki manual, we simply link to the compatibility page.
Also in the README, there is a section with notes about individual
games. Now in the wiki manual it seems slightly ridiculous to do this:
we should simply link to the wiki page for that game, but this makes
converting from wiki manual to readme much more difficult.

Hopefully you can see where my concerns lie. It would be great if,
when something changes, the dev could add it to the docs in one place
and run an "update docs" script or something, but I just can't see how
that could work. I've spent quite a bit of time on the wiki manual
recently, but I'm loathed to spend much more if we're going to get to
a 1.0 release (which would, admittedly, be great), then the docs just
fall apart because they're too difficult to update.

Does anyone share my worries?



Henry