[Scummvm-devel] Documentation

[Max Horn]

Hiya folks,


I am sure all of you will agree that better docs would be nice... well, 
I at least do think so :-). Of course writing docs is not something 
everybody likes *cough* *cough*. :-)

But maybe we can find some people who are willing to help. To that end, 
it would be good to determine what exactly we are missing for a proper 
user's manual (and what other kind of docs we would like to have etc.).


Fact is, our README is much more than a simple README, it's really more 
a manual. A manual which in some places is a bit terse, though. So here 
is what I think should be done:


* We have LaTeX docs now, fine - but how can those be turned back into 
a text file? I.e. we can generate DVI, PDF, PostScript, HTML, RTF and 
probably more. But can we generate plain text? If so, how? I asked this 
before but never got a reply (BTW, this issue was the reason why I left 
LaTeX out of my list of potential doc formats in our TODO. Formats I 
did consider included: DocBook, texinfo, nroff/troff, tbook, xml2doc)

* Not being able to generate plain text is not necessarily a problem, 
though: We could decide to turn the README back into a more standard 
README: That is, only give a very brief overview and quickstart, then 
refer to the manual (which should be included in the ScummVM binary 
package, for example as HTML or PDF). And of course the manual would be 
online on our website, as HTML, and PDF

* The LaTeX docs are not really taking advantage of LaTeX: for example, 
using bold/italics to highlight text; Code sections (with excerpts from 
e.g. the config file) should be formated in courier; and other things.

* The structure of the "manual" is lacking. I recently put a proposal 
for a revised doc structure into our TODO file. I reproduce it below 
(note that this is just a rough first draft, any suggestions and ideas 
are most definitely welcome :-)

   + Introduction
     - What is ScummVM
     - History
     - Contacting the developers
     - Reporting bugs
   + Supported Platforms
   + Supported Games
     - Copy Protection
     - Simon
     - BS notes
     - Using mac data files
   + Getting started
     - How to get ScummVM (binary, source)
       - Binary (Where to get packages for your system; how to install 
them, for each OS)
       - Compiling (with more detail than now)
     - First steps (basic setup, getting a first game to run)
   + Running ScummVM
     - Command line options
     - Hot Keys
     - Savegames
   + Configuration
     - Using the launcher
     - All config file switches in detail
     - Graphics Filters
     - Music and Sound (mostly like now; maybe under the 'Configuration' 
section)
   + Glossary? (explaining abbreviations etc.)
   + Credits
   + Index? (would be nice, for example 'fullscreen' could link to the 
hotkey,
      the config file setting, and the command line option)

* The above suggested structure change highlights another problem with 
the LaTeX docs: the filenames hard code the section structure - not 
good. Better to have 'logical' filenames, i.e. names which reflect the 
content, not the chapter number. That way, we don't end up with the 6th 
section contained in 09.tex :-)

* Lastly, some sections badly need improvement. For example, I'd like 
to improve the build instructions for Mac OS X, and I guess some of the 
other build instruction sets could need that, too. Overall, our docs 
assume that the user knows the command line pretty well. Since I am a 
mac user, you may not be surprised that I don't like that too much ;-). 
If you know me you'll also know I am not eager to write docs for 
non-CLI users, either, but overall I think it would be a good thing for 
the project, and for us, if we made life easier for "plain" users. (We 
improve our potential 'market share', and we might reduce the support 
work load) :-)

* More OS specific sections! I want there to be more information for 
PalmOS/WinCE/Dreamcast etc. users! Like, a list of Palms which are 
supported; which are *not* supported (and if there is hope for them to 
be ever supported, or not). Similar for WinCE, if necessary. And then, 
information how to setup ScummVM on these machines, and information 
about typical problems and how to solve them, etc. etc. And links to 
appropriate help forums :-)

* So far the manual. Another part of our docs which we should review 
and improve is the FAQ. A plain text version of it maybe could be 
shipped with each ScummVM binary package. I haven't thought about 
improving the FAQ much, though. Of course the platform specific issues 
might fit in here well, too (see above, when I talk about 
PalmOS/WinCE/Dreamcast)




Cheers,

Max