A call for help: The Manual

[Llorean]

As most of you know, we have a manual for Rockbox. As many of you also know, often people complain that it is to confusing or simply write their own, often somewhat lacking, guide and then distribute it.

I would like to ask for help. We've put a lot of work into the manual but all things can be improved. My specific interest at this time is the installation section. How can we make it clearer. Where can ambiguity be removed. How can we keep all the different manuals as similar as possible without sacrificing ease of use? We welcome all help but if you aren't going to write out new text, be very clear in what you mean. Just pointing out weaknesses does not help without also offering a solution.

Part two of this task is RBUtil. I believe it needs its own manual, as well as well developed special sections in the various player manuals covering any special differences in how its features may work with that player.

[Mikerman]

It may be useful to compile a list of what is missing in the manual (so the gaps, then, may be filled in by people).

For example:

--  Folder advance plug-in; and how to except folders from it.
--  Virtual keyboard:  how to personalize the keyboard/set a different keyboard up.

[bluebrother]

We already have a wiki page for this (back to the times when I was actively working at the manual). Look at http://www.rockbox.org/wiki/ManualTodo While that page deals with internal details of the manual itself it can still be helpful to add missing / outdated sections even if you don't know how to use LaTeX. And how about considering to use it? It isn't that hard and you'll find quite some helpful people on IRC (and I bet the gratitude of a bunch of users )

[Llorean]

To clarify, for Godeater and others, in terms of a manual for RBUtil, I don't think it needs to be huge, but I think it's never wise to tell a user to just jump in and they'll figure it out. Ipodpatcher basically holds your hand. You run it andit asks questions. RBUtil has a variety of options and some people don't know what all it can do, or what the real difference between some options are. As it grows, this becomes more of a concern. While RBUtil is explained in the wiki, I think we shouldn't require users to go to the wiki. Instead it should have a manual giving bsic explanations. Mainly this need is based on gauging the reactions too the software on a to-be-nameless test dummy. For example, while the instruction for the battery toggle isn't in too bad of a place during the Gigabeat bootloader install, users will likely assume that's just progress info and not read it. Someone following a manual, which is hopefully more likely than someone following the wiki, will in theory see something like "be sure to check the output for any additional steps you may have to take on the player itself."

[GodEater]

I don't question the fact that RBUtil needs instructions, I was just surprised you were suggesting a seperate manual for it. I'm sure it doesn't need something like that - just more detail on the installation section of the existing manual ?

[Llorean]

The fact is though that you can use it for talk file generation, theme instalation, and various other things. At first I thought maybe it needed its own chapter in the manual but am leaning toward its own guide. The use of it for instalation belongs also in the player manuals but I think as a tool it needs more documentation for the other tabs too.

[Mikerman]

We already have a wiki page for this (back to the times when I was actively working at the manual). Look at http://www.rockbox.org/wiki/ManualTodo

Thanks for noting that here and providing the reminder to it.

[MarcGuay]

If anyone with commit power and an interest in the manual wants to take a look at this link to flyspray, there are quite a few patches waiting for comments, criticism, or inclusion.

http://www.rockbox.org/tracker/index.php?string=&project=1&has_attachment=1&type%5B%5D=&sev%5B%5D=&pri%5B%5D=&due%5B%5D=&reported%5B%5D=&cat%5B%5D=34&status%5B%5D=open&percent%5B%5D=&opened=&dev=&closed=&duedatefrom=&duedateto=&changedfrom=&changedto=&openedfrom=&openedto=&closedfrom=&closedto=&do=index

[Chronon]

I just got my home computer running again (not on a LiveCD this time!).  I just got a build environment set up (Debian).  So I will be taking some time to see if I can improve the clarity where I can.