[Scummvm-devel] Documentation

[Henry Bush]

> What would *you* prefer, as a very active editor?
I'm afraid I don't have a "magic bullet". I will happily edit whatever
needs editing, I just don't want to have to do it twice :-). I think
the problem stems from the fact that we want two different manuals:
the wiki manual (which is a multi-page manual) and a single document,
pdf (or other) version. There doesn't seem to me to be a simple way to
convert from multi-page wiki to single pdf, or vice-versa. So that
says to me that we should concentrate on one or the other. That is
really for the team to decide, but IMHO the single pdf makes a bit
more sense (as this could be viewed on the web and distributed with
ScummVM, in pdf or text format).

> Ideally, there would be a single "database" (and that could be a simple
> text file or a real SQL db, I use the word in the most general sense)
> which contains information like that, and other spots would
> (semi)automatically be updated when it gets changed. Right now, that's not
> really possible, I think.
This would be ideal. If all games were in a database along side a
description, the platforms it's available on, whether it is fully
supported, etc, and all e.g. ports were in a database that linked to
the games playable on that port, etc... that would be heaven! OK,
exaggerating slightly, but it would certainly solve a lot of
problems...

> Other parts of the docs, however, are relatively static. There, the main
> problem is to keep the README and the "manual" in sync. However, once we
> have a real manual, that will becomes a non-issue -- we will then just
> change the README to a very very short file with only the bare bone
> information, and referring to the manual.
Another reason to concentrate on the single document version ;-) I see
your point here, when the manual is finished, we won't need a README
(at least, not in its current form).

Anyone have experience of what other (well-documented) open source projects do?


Henry