release
dev builds
extras
themes manual
wiki
device status forums
mailing lists
IRC bugs
patches
dev guide



Wiki > Main > ManualStructureTalk (compare)

Difference: ManualStructureTalk (r5 vs. r4)

Discussion of a new structure for the manual

A note on structure

As the designer of the manual structure from the pre-LaTeX days, I had a very specific purpose in mind. Rockbox is a highly complicated piece of software, but most of that complexity is of little or no interest to many users, and first time users in particular. The structure of the manual should reflect the requirements of a new user as they unfold. A more advanced user will of course hop through the manual to the sections they need, and while it is still important that the information be laid out in a logical way the ordering of the manual sections is of most importance to a user coming to Rockbox for the first time.

With that in mind, consider the order in which a new user coming to Rockbox for the first needs their questions answering. The way I think of this is as follows:

  • What is Rockbox? What does it do?
  • Is there anything general I need to know to understand this manual? (Hopefully not - if we need to explain how to use the manual, there's a good chance it's not simple enough.)
  • How do I get Rockbox onto my DAP? (Including any steps necessary for getting the blind interface to work.)
  • OK it's booted, so what the heck is going on?
  • How do I navigate around the interface?
  • How can I make it play some music?
  • OK - what else can it do, then?
  • Right, how do I make it work the way I want - configuration etc.?
  • What are all of these plugins for?
  • What sort of really hairy stuff can I do if I want to get my hands dirty?

Hopefully this is of some use in working out how to structure the manual. ChristiScarborough

New Structure

As already started brainstorming it would be good to rework the manual structure making it easier for new users to catch the relevant information for starting first. Also, some chapters are a bit strangely sorted.

Issue What needs to be done Status Worked on by who?
Quick start chapter Subsections "first contact", "rockbox concept", "menu overview", "customizing" brainstorming  

Proposed Structure

  1. Introduction
    1. Welcome
    2. Getting more help (big hint to the tracker guidelines!)
    3. Naming conventions
  2. Installation
    1. Prerequisites (zip, recognize your drive letter, text editor for cfg / wps (note unicode)
    2. Installing the bootloader (name the rescue mode if any exists, also introduce bootloader usb mode if available)
    3. Installing rockbox (note the extra fonts package)
    4. Updating rockbox
    5. Uninstalling rockbox (note the possibility to leave the bootloader, e.g. for bootloader usb mode if present)
  3. Quick Start
    1. "First Contact" (starting the player, what you'll be looking at now with default settings, guide to the next ...)
      1. starting the player
      2. the default view
      3. basic controls
    2. The Rockbox concept(s): playlists, main screens, etc.
      1. main screen is the file browser
      2. playlists
      3. menus
      4. context menus
    3. Menu Overview (with the complete menu structure)
    4. Customizing Rockbox (esp. Themes, external ressources)
  4. The Main Menu
    1. like already there
  5. Sound Settings
    1. already there
  6. General Settings
    1. already there
  7. Plugins
    1. Overview
    2. Plugins split into groups like already done
  8. Advanced Configuration
    1. Customizing the UI, cfg files
    2. Themes
    3. wps
    4. Rolo
  9. Appendix
    1. supported file formats
    2. wps tags
    3. cfg values
    4. feedback
    5. changelog?
    6. credits
    7. license for rockbox
    8. license for the manual

Proposal sandbox

Use this section to play around with ideas, comments etc to be merged into something we work towards (i.e. the proposal above). Feel free to change anything here. Let's work towards a structure that is logical, intuitive and easy to follow.

  1. Introduction i. No changes
  2. Installation i. No changes
  3. Quick Start i. "First Contact" (starting the player, what you'll be looking at now with default settings, guide to the next ...)
      1. starting the player
      2. the default view
      3. basic controls
    1. The Rockbox concept(s): playlists, main screens, etc.
      1. main menu (aka root menu)
      2. playlists
      3. menus
      4. context menus
    2. Menu Overview (with the complete menu structure) <-- This should be moved to the appendix in my opinion. -- MartinArver - 02 May 2007
    3. Customizing Rockbox (esp. Themes, external ressources)
  4. Browsing and playing ( -- MartinArver - 02 May 2007 . This should follow the structure of the menu imo.)
    1. Files
    2. Database
    3. Now playing screen
  5. Recording
  6. FM-radio
  7. Settings i. Sound settings i. General settings
  8. Plugins
  9. System
  10. Advanced topics i. Maybe tips & tricks
  11. Appendix

r5 - 20 May 2007 - 10:20:20 - ChristiScarborough

Revision r5 - 20 May 2007 - 10:20 - ChristiScarborough
Revision r4 - 02 May 2007 - 07:15 - MartinArver
Copyright by the contributing authors.