[Scummvm-devel] Brainstorming about ScummVM Manual

[Max Horn]

Am 24.01.2008 um 01:23 schrieb Henry Bush:

> Hello all,
>
> Yes it's me again, going on about the manual ;-)

Hi Henry!

I'll try to sum up my thoughts on what our needs are when it comes to  
(User) documentation, rather than answering to your email in detail.   
The reason is that I think we might loose our goal out of sight when  
trying to focus too much on the means. And maybe we first need to  
agree on what "our" goals *are* anyway ;-).

What I envision is that all our users, current and future ones, get a  
single place where the majority of their questions get answered in a  
clean and transparent fashion. Note that "single place" does not  
necessarily mean "a single file, a single user manual", it could also  
be a whole website (e.g. the Wiki). Which one to use (or even both?)  
is a matter of implementing the goal, the means to an end, not the  
end itself.

So, first, what are typical questions that cause users to seek for  
info (or which cause us to point them *politely* to them, after being  
bugged for the Nth time on the forums *g*) ? I guess it's something  
like this, in *roughly* the order people might ask them:

* What is ScummVM?
* What are the requirement for using it? Can I use it? Specifically,  
on *my* favorite device(s) ? I.e. which system are supported ?

* Cool, so which game does it support?
* Which games are  supported on *my* device?
* Where can I get those game?

* How can I obtain & install ScummVM?
* How do I install game X on my device?
   - In particular, how do I use the launcher? How do I copy files to  
an iPhone etc.?
* How do I control ScummVM? (port specific hotkeys / button combos /  
etc.)

* "Advanced": How to compress data files?
   (advanced because it's not that trivial; but for many ports, it's  
actual vital, so good docs are important, and in fact we should  
strive to simplify this; but that's another story)

* Game specific stuff where needed

* Troubleshooting / FAQ: Questions about particular games
* Troubleshooting / FAQ: Questions about particular ports
* more FAQs

* For advanced users: How to compile it myself (clearly can be separate)


Maybe more, but I think these cover most of the urgent stuff.

Some things in that list are generic and the answers are the same for  
everybody. Some are port specific. Some are mixed. The first thing  
one can wonder about (and this is what you asked, I understand): Do  
we try to present all answers together, for all ports? Or do we  
rather have several documents, each geared towards a specific platform?

Secondly, lots of that info is already available. The problem often  
is *finding* it because it is spread out across too many places: The  
Wiki (and its many subpages, which often are not optimal connected),  
our website (think of the compatibility page), the README, port  
specific READMEs and websites, several forum posts, etc.. What can we  
do to help users find the stuff relevant to them?


Currently, I tend to this answer: Port specific documentation makes a  
lot of sense, because most users already know on which system they  
want to use ScummVM. Of course it should adhere to some quality  
criterions, and it should not needlessly duplicate information easily  
available (and linked to!) elsewhere. Also, we still need an overview  
page comparing all ports and which games they support, for those  
people who want to know whether to buy a Symbian phone (and which), a  
WinCE PDA or Nintendo DS. And for general stuff, we should have a  
general place.

So, What I would envision is this: Our documentation is spread across  
multiple documents / wiki pages. We have a "Documentation portal",  
where we link to the various parts. We still have the user manual,  
and it answers all questions it can answer globally, i.e. where the  
answer is the same almost everywhere. In places where it can't do,  
resp. where some ports are different, it points to the "port specific  
manuals".

And then we have a page / a subsection of the documentation portal,  
which lists all port specific manuals. And these in turn remain as  
is, resp. are *all* moved to the Wiki (or all moved to DocBook, or  
whatever). Plus, we make a "template" for them, so that they adhere  
to some common structure (here, I use "template" loosely, and am not  
referring to Wiki templates). I.e. each "port manual" should list, in  
some fixed order:
* "About" the port (e.g. briefly answer such things as "What is a  
GP2x" etc., mabye point to relevant Wiki entries / websites)
* requirements (RAM...), supported devices
* supported games
* installation instructions (including info on how to install  
homebrew software / downgrade firmwares etc. if necessary)
* port specific usage instructions: Controls, key mappings etc.
* port specific FAQ
* a link to the compilation instructions, which should be kept  
separate, though
* Resources, external links (forums, wiki, ...)
* and possibly, extra stuff, like "history of the port"

Some ports already do that, but not all. And some have the  
information, but on external sites (like the iPhone in the Wiki, or  
the DS on a separate page under Neil's control). I really would like  
to see them all in the Wiki. This way, they are easy to find, and  
easy to edit. And if some porters prefer to retain control over their  
docs, well, fine by me, but it still helps to have them in a central  
place: users can find them better; and if a porter steps down for  
whatever reasons, the docs are not lost / are still editable / do not  
change their place on the net.

That's how *I* think currently we should do things. But this is by no  
means fixed in stone ;-)

[...]

> So my question is this: should the ScummVM manual contain absolutely
> EVERYTHING about ScummVM? By that I mean should it incorporate
> documents such as (for example):
>
> http://wiki.scummvm.org/index.php/SymbianOS_FAQ
> http://forums.scummvm.org/viewtopic.php?t=936 (SirDave's WinCE manual)
> http://forums.scummvm.org/viewtopic.php?t=3334 (GloKidd's PalmOS  
> manual)
> http://wiki.scummvm.org/index.php/Compiling_ScummVM (+ individual
> compilation instructions for each port)

Another important one:
<http://forums.scummvm.org/viewtopic.php?t=4752> iPhone install  
instructions


Cheers,
Max