User Manual/TODO

Introduction

I see several ways in which the user might use a ScummVM manual.

• A new user will arrive: I have game XXX and I was told that ScummVM can help me to play this game on platform YYY. How can I run this game with ScummVM?. A good way to help that user would be to have a Quick Start section, something that the current manual is lacking.

• More experienced user (or the same user a bit later) will ask more complex questions or will want more details. How can I get a better sound? What sound settings should I use?. For this kind of more advanced documentation I would simply take the different sections of the Quick Start and break them into different pages in which we can add more details.

• The last approach is quite different: the user with the ScummVM window in front of him might ask himself what is this button? What does it do? Here instead of a workflow approach (How To?), we have a GUI oriented approach (What Is?).

The following reorganization tries to address all these approaches.

Manual Proposed Reorganization

1. Introduction

What is ScummVM?

2. Quick Start

This would look like a platform-independent tutorial of the whole process, up to launching a game. One of the freeware game can be used as an example so that the user can try it himself.

This should be short and well illustrated. All subsections here would also have a link to the more detailed section.

2.1 Getting and installing ScummVM
2.2 Installing game for use with ScummVM
2.3 Adding Games in ScummVM
2.4 Running Games in ScummVM
2.5 Where to get help?

3. ScummVM Interface

3.1 Main Window
3.2 Options
3.3 Game settings 
3.4 In-game menu (with a list of games that keep to their own menus)

4. Using ScummVM

4.1 Getting and installing ScummVM (on all platforms)
4.2 Setting up ScummVM (describing the settings and command-line parameters)
4.3 Installing games for use with ScummVM (covering multi-CD games, additional files like kyra.dat, and extracting/converting audio tracks)
4.4 Adding and Running a game in ScummVM (and creating batch files)
4.5 Setting up a game in ScummVM (adjusting per-game settings, describing why 3x scaler makes 640x480 games run in a smaller window than oldies...)
4.6 Removing a game from ScummVM
4.7 Uninstalling ScummVM - ? Why would they even think about that?!

5. Getting help

5.1 FAQ - ? Would threads like these:
'Why isn't my Torin's Passage detected by ScummVM?' - 'It is probably not supported by now. See compatibility page here (link).'
qualify as 'frequently asked'? Or 'There is no sound'? 'My game crashes'?
5.2 Contacts

6. Appendix

Contains comprehensive technical information.

6.1 Command line options
6.2 Config file description
6.3 Tools

Discussion on Proposed Reorganization

• Do we need a FAQ there? There is already an FAQ on the web site? Maybe we could have a more detailed FAQ, i.e. for each question we would not just have two or three lines but a more complete answer (with illustrations if needed).

• For the nearly identical items (e.g. ScummVM's 'Options' and 'Edit game' windows) it would probably be better to duplicating Manual's contents - thus never having to make reservations for numerous tiny peculiarities.

• The manual in this structure might not be optimal for users wanting to use the manual on a specific platform. They would have to look for bits on different pages that contains many information not relevant for that platform. I don't know how to improve that. Maybe we can have a page similar to an index with the list of platforms and for each one links to the relevant parts in the documentation.

• Should the ScummVM interface and Using ScummVM section be each on a single page or have on page for each sub-section? I would prefer the later because otherwise we might get very long pages and I think it is easier to find information on several well organized pages than on a single long page.

TODO

Reorganize the content as described above

I would like to keep the history and discussion for the existing pages of the current documentation. Therefore some of the pages will be kept or renamed. We will need to create new pages.

Until I make all the modifications in the structure, work can go on on the existing pages and the new pages can be created.

List of pages after reorganization:

+ Introduction

+ Quick Start

ScummVM interface (or everything on one page?)
 + Main Window
 + Options
 + Game settins
 + In-game menu

Using ScummVM
 + Installing ScummVM
 + Setting up ScummVM
 + Installing games for use with ScummVM
 + Adding and running a game in ScummVM
 + Setting up a game in ScummVM
 + Removing a game from ScummVM
 + Uninstalling ScummVM

Getting Help
 + FAQ
 + Contacts

Appendix
 + Command line options
 + Config file description
 + Tools

Here is the mapping between the old pages and new pages I intend to do:

Introduction -> Introduction
Getting started -> Installing ScummVM
Running and using ScummVM -> Adding and running a game in ScummVM
Game Specific Instructions -> Installing a game for use with ScummVM
Configuration -> Setting up ScummVM
Appendix: Tools -> Appendix: Tools

And a list of pages that will need to be created:

Quick Start

ScummVM interface (one or four pages?)
 + Main Window
 + Options
 + Game settings
 + In-game menu

Setting up a game in ScummVM
Removing a game from ScummVM
Uninstalling ScummVM

FAQ
Contacts

Command line options
Config file description

I (Criezy) would like to reorganize the content of the manual on the weekend of August 1.

Here is how I plan to proceed:

1. Add a notice on the manual entry page (reorganization of manual structure underway)
2. Rename existing pages
3. Create new pages (if not already done)
4. Update manual entry page
5. Fix all links to manual pages/sections.
6. Move content around
7. Remove notice from manual entry page

Add ScummVM and game installation instructions

We need to add the instructions for the following platforms:

• Fedora Core / RedHat
• GP2X
• Maemo
• Nintendo DS
• PS2
• Symbian
• Wii
• Nintendo GameCube

We might be able to get the information from:

• the wiki platform page
• the port forums, but we need to make sure it is up to date (ask port maintainer).
• ask in the port forum if the information is not already there
• ask directly the port maintainer (I am not sure they all visit the forums).

Add controls for embedded devices

We need to add controls for embedded devices (devices that do not use a mouse and keyboard). It is missing for the following platforms:

• PS2
• Symbian
• GameCube
• Wii
• Maemo
• ... [TODO: complete list]

Add descriptions of GUI features

The descriptions for the following GUI features need to be added or completed

• GMM
• Search field
• Launcher's 'Load Game' window (with a list of games that cannot be loaded this way).
• [TODO: complete list]