[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