Difference between revisions of "User Manual/TODO"

From ScummVM :: Wiki
Jump to navigation Jump to search
(→‎Discussion on proposed reorganisation: adding comment received from Svipur by email)
 
(46 intermediate revisions by 5 users not shown)
Line 1: Line 1:
{{Infobox_TODO|
taskname=User Manual TODO|
techcontact=The ScummVM Team|
subsystem=Documentation|
}}
== Introduction ==
== Introduction ==
I see several ways in which the user might use a ScummVM manual.
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.
* 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.
* 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.
Line 8: Line 14:
* 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 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 reorganisation tries to address all these approaches.
The following organization tries to address all these approaches.
 
== Manual Proposed Reorganisation ==
1. Introduction
 
What is ScummVM?


2. Quick Start
== User Manual Structure ==
1. Introduction
  What is ScummVM?


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.
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 Installing ScummVM
  2.2 Installing a game for use with ScummVM
  2.3 Adding a game in ScummVM
  2.4 Running a game in ScummVM
  2.5 Where to get help?


This should be short and well illustrated. All subsections here would also have a link to the more detailed section.
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)''


  2.1 Getting and installing ScummVM
  4. Using ScummVM
2.2 Installing game for use with ScummVM
  4.1 Installing ScummVM ''(on all platforms)''
2.3 Adding Games in ScummVM
  4.2 Configuring ScummVM ''(describing the settings and command-line parameters)''
2.4 Running Games in ScummVM
  4.3 Installing a game for use with ScummVM ''(covering multi-CD games, additional files like kyra.dat, and extracting/converting audio tracks)''
2.5 Where to get help?
  4.4 Adding and Running a game in ScummVM ''(and creating batch files)''
  4.5 Configuring 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?!''


3. ScummVM Interface
5. Getting help
3.1 Main Window
  5.1 FAQ ''- ? Would threads like these:
3.2 Options
  'Why isn't my Torin's Passage detected by ScummVM?' - 'It is probably not supported by now. See compatibility page here (link).'
3.3 Game settings
  qualify as 'frequently asked'? Or 'There is no sound'? 'My game crashes'?''
3.4 In-game menu ''(with a list of games that keep to their own menus)''
  5.2 Contacts
  5.3 Reporting bugs


4. Using ScummVM
  6. Appendix
  4.1 Getting and installing ScummVM ''(on all platforms)''
  Contains comprehensive technical information.
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)''
  6.1 Command line options
4.4 Adding and Running a game in ScummVM ''(and creating batch files)''
  6.2 Config file description
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...)
  6.3 Tools
4.6 Removing a game from ScummVM
4.7 Uninstalling ScummVM ''- ? Why would they even think about that?!''


5. Getting help
== Discussion on the User Manual Structure ==
5.1 FAQ ''- ? Would threads like these:
* 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).
'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
* 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.


Contains comprehensive technical information.
* 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.
** 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.
** We can have a Platforms page with the info sorted by platform. The content (ScummVM installation, Game installation and controls) could be written in templates so that it is not duplicated and can be used in several places (e.g. User Manual, User Manual Platforms page, wiki platform pages).


6.1 Command line options
* 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.
6.2 Config file description
6.3 Tools
 
== Discussion on proposed reorganisation ==
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.
 
== TO DO ==
=== Reorganise the content as described above ===
I ([[User:Criezy|Criezy]]) would like to reorganize the content of the manual on the weekend of August 1.
 
Here is how I plan to proceed:
# Keep current manual as it is while I am working on the reorganization
# Lay down the new skeleton (i.e. create new pages, with _new extension if it clashes with pages of old manual)
# Freeze content of old doc (can we make a page read-only?) From that points all the contributions should be done on the new pages.
# Copy all the content from old to new manual.
# Remove old manual (or move it to User_Manual_old ?)
# Rename pages (if needed) of new manual. Fix all links to manual pages/sections.


== TODO ==
=== Add ScummVM and game installation instructions ===
=== Add ScummVM and game installation instructions ===
We need to add the instructions for the following platforms:
We need to add the instructions for the following platforms on the [[User Manual/Installing ScummVM|Installing ScummVM]] and [[User Manual/Installing a game for use with ScummVM|Installing a game for use with ScummVM]] pages:
 
* Atari
[TO DO: add list]
* BeOS
 
* Fedora Core / RedHat
* GP2X / GP2XWiz
* PS2
* Symbian
* Wii
* Nintendo GameCube




Line 85: Line 88:
* ask in the port forum if the information is not already there
* 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).
* ask directly the port maintainer (I am not sure they all visit the forums).
This information is to be displayed on several pages (e.g. the User Manual, the platform pages). To avoid duplication, we can use two templates for each platform, one for ScummVM installation and one for game installation, that contain the relevant information.


=== Add controls for embedded devices ===
=== 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:
We need to add controls for embedded devices (devices that do not use a mouse and keyboard) on the [[User Manual/Adding and Running a game in ScummVM|Adding and Running a game in ScummVM]] page.
For the following platforms there is a link to the platform pages. This should be changed so that it is directly visible in the User Manual.
* Windows CE
It is completely missing for the following platforms:
* PS2
* Symbian
* GameCube
* Wii
 
=== Requirements ===
The requirements section on the [[User Manual/Installing ScummVM|Installing ScummVM]] page is incomplete.
* Update list of supported platforms, platforms that are not maintained anymore and third party unsupported platforms. The PS2 for example is not in the correct category and the Android port is missing altogether.
* Add minimum memory, OS (or firmware) version, screen size... required to run ScummVM on each platform.
 
=== Compiling from source ===
The compiling from source section on the [[User Manual/Installing ScummVM|Installing ScummVM]] page needs to be written. Here are some ideas:
* Point to the Compiling ScummVM page, resp. integrate that here.
* List all required libs; where to get them; how to install them
* List all optional libs etc.
* We could separate this by OS, or by compiler/dev system. I think the current split in the README (section 9.0) isn't too bad.


[TO DO: add list]
=== Uninstalling ScummVM ===
The page [[User Manual/Uninstalling ScummVM|Uninstalling ScummVM]] needs to be written (or removed). I suppose there will be different instructions depending on the platform (e.g. Windows, Linux, Mac, iPhone).


=== Add descriptions of GUI features ===
=== Appendix ===
The descriptions for the following GUI features need to be added or completed
* Write [[User Manual/Appendix: Config file description|config file description]]
* GMM
* Write the [[User Manual/Appendix: Music and sound#Using compressed audio files|Using compressed audio files]] subsection.
* Search field
* Check the [[User Manual/Appendix: Tools|list of tools]], their description and their command line arguments are up to date.
* [TO DO: complete list]

Latest revision as of 18:59, 7 October 2011

TODO List
Name User Manual TODO
Technical Contact(s) The ScummVM Team
Subsystem Documentation

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 organization tries to address all these approaches.

User Manual Structure

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 Installing ScummVM
 2.2 Installing a game for use with ScummVM
 2.3 Adding a game in ScummVM
 2.4 Running a game 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 Installing ScummVM (on all platforms)
 4.2 Configuring ScummVM (describing the settings and command-line parameters)
 4.3 Installing a game 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 Configuring 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
 5.3 Reporting bugs

6. Appendix
 Contains comprehensive technical information.
 
 6.1 Command line options
 6.2 Config file description
 6.3 Tools

Discussion on the User Manual Structure

  • 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.
    • 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.
    • We can have a Platforms page with the info sorted by platform. The content (ScummVM installation, Game installation and controls) could be written in templates so that it is not duplicated and can be used in several places (e.g. User Manual, User Manual Platforms page, wiki platform pages).
  • 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

Add ScummVM and game installation instructions

We need to add the instructions for the following platforms on the Installing ScummVM and Installing a game for use with ScummVM pages:

  • Atari
  • BeOS
  • Fedora Core / RedHat
  • GP2X / GP2XWiz
  • 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).


This information is to be displayed on several pages (e.g. the User Manual, the platform pages). To avoid duplication, we can use two templates for each platform, one for ScummVM installation and one for game installation, that contain the relevant information.

Add controls for embedded devices

We need to add controls for embedded devices (devices that do not use a mouse and keyboard) on the Adding and Running a game in ScummVM page. For the following platforms there is a link to the platform pages. This should be changed so that it is directly visible in the User Manual.

  • Windows CE

It is completely missing for the following platforms:

  • PS2
  • Symbian
  • GameCube
  • Wii

Requirements

The requirements section on the Installing ScummVM page is incomplete.

  • Update list of supported platforms, platforms that are not maintained anymore and third party unsupported platforms. The PS2 for example is not in the correct category and the Android port is missing altogether.
  • Add minimum memory, OS (or firmware) version, screen size... required to run ScummVM on each platform.

Compiling from source

The compiling from source section on the Installing ScummVM page needs to be written. Here are some ideas:

  • Point to the Compiling ScummVM page, resp. integrate that here.
  • List all required libs; where to get them; how to install them
  • List all optional libs etc.
  • We could separate this by OS, or by compiler/dev system. I think the current split in the README (section 9.0) isn't too bad.

Uninstalling ScummVM

The page Uninstalling ScummVM needs to be written (or removed). I suppose there will be different instructions depending on the platform (e.g. Windows, Linux, Mac, iPhone).

Appendix

Retrieved from "https://wiki.scummvm.org/index.php?title=User_Manual/TODO&oldid=16873"