[Scummvm-devel] ScummVM 1.0 and "The Manual"
Max Horn
max at quendi.de
Sun Jan 14 21:46:16 CET 2007
Hi folks,
so after a brief chat with Ender and Sev, it seems we agree that we
could aim for 1.0 now Essentially, we agreed that we are "good
enough", with the exception that we are lacking when it comes to end-
user documentation. Well, and of course the usual release things, of
course (fixing known bad regressions and crashes, getting ports up-to-
speed etc.).
First off, does anybody have any other concerns regarding aiming for
making the next release be "1.0" ? (and I am implicitly assuming we'd
make "1.0 beta" releases, too, of course).
So, that leaves my good old main concern: What to do about docs / a
manual / "User's Guide"...
As a first step, I recently went through the README to correct at
least some of the worst out-of-date problems, and also added some
TODOs to do it that would have to be resolved before we can make a
release with it (no matter what we call that release). The data in
there is a good foundation, though it is neither structured very
well, nor particularly friendly to unexperienced users.
So, we can base a manual on it, and I already begun work in that (in
form of "manual.xml" in the "docs" SVN manual, using DocBook) some
time ago. IMO with some dedicated effort it should be possible to
flesh that out to a good manual in relatively short time.
Some of you might argue that we now have a Wiki into which one could
put lots of documentation and stuff. So do we really still need a
manual or even a big README?
My thought is: Yes, we still need a separate manual! Granted, a wiki
is nice when it comes to collaborate editing, but that in itself
doesn't ensure that anybody writes docs, let alone high quality docs...
But on the minus side a Wiki is something inherently tied to being
online. You can't easily download it or, god forbid, print it. With a
manual, you can do all of these; a PDF or HTML manual could be stored
and viewed on a hand held device, printed, copied to HD etc. -- and
in addition would *also* still be available on the net.
The plan is to have an online HTML version of the manual, and also
ship a HTML and/or PDF version with ScummVM itself. Other output
formats are possible. We can also make a text version (simply by
rendering the HTML one with lynx/links/w3m/...).
The current work is using DocBook. Maybe some of you want a different
format. Well, if you have a really good suggestion, say it, but IMO
it's far more important to finish the structure and content of the
manual. We can still change to a different format later on if we want
to -- a conversion is work, yes, but rather mechanical and much
easier to do than to *create* the manual in the first place.
One of the problems with the DocBook manual (and FAQ, BTW) is that
people so far had a hard time editing it, as it was difficult to
convert the XML source to HTML/PDF/text. For this reason I spent some
effort trying to simplify using the docbook stuff in the "docs" SVN
module. I added a README explaining what packages one might need and
how to use the Makefile. I'd be very happy if some of you could try
this. Don't hesitate to ask me for help should you have trouble to do
so; I am very interested in augmenting the README, and especially in
adding a guide for Windows users.
Bye,
Max
More information about the Scummvm-devel
mailing list