Rockbox

Thank you for this effort. One thing that I noticed on a quick scan of your patch is the section regarding booting to the manufacturer’s firmware to connect via USB. This may be true for the Sansa, but it is not true for all players. For example, it is not required at all for the H120 or the Gigabeat. Perhaps this chapter of the manual should include a “Connecting to USB” section explaining how to connect to USB for each platform.

This diff has a number of issues:
- you removed the hint about the player description for blind users. I don’t think this should get removed. While it’s obvious for sighted readers this doesn’t automatically apply for blind readers.
- you name the first section “Loading music”. I disagree to start with this: the getting started chapter should describe how Rockbox interface looks like first, not how to sync it.
- it is wrong that you need to manually reboot into the OF for disc access. This applies to the sansa _only_. Ipods reboot to disc mode, and most other players have hardware usb mode which toggles just fine.
- presenting a list of features (”plays many formats including …“) doesn’t make sense in the introduction. The “getting started” chapter should not tell the user what he can do but how he has to operate the system successfully.
- “Rockbox default theme is not very pretty” – that’s no wording I like to see in the official manual and it isn’t true. If you like or dislike the default theme is heavily depending on your taste, and to be honest, I really like the default wps on my mini. The manual shouldn’t judge if something is “pretty” or not. Also, themes shouldn’t be presented too early – the important thing is that users get the idea behind Rockbox’ interface, not behind themes.
- the reworked Playlists section gets the facts wrong: Rockbox will _not_ play simply the next file in the folder, it will play the next file in the playlist. If you started playback from the file browser this is in fact the next file in the folder. If you use the database or a playlist it’s not necessarily. While this gets somewhat clarified later writing this way simply causes confusion.
- not all players have a sleep timer. Besides, this is nothing I’d like to see in an introductory chapter.

To sum it up, while I really like someone trying to improve the manual I don’t like the way it’s written and consider it more confusing than the original text.

Thanks for the comments, I didn’t know about the USB - I can change it.

you removed the hint about the player description for blind users. I don’t think this should get removed. While it’s obvious for »sighted readers this doesn’t automatically apply for blind readers.

I do not think I removed any of the stuff for blind users, what is missing?

- you name the first section “Loading music”. I disagree to start with this: the getting started chapter should describe how »Rockbox interface looks like first, not how to sync it.

I put this in because my first problem when starting with rockbox was figuring out how to get some music on it and where to put it and it what format. I was not easy to find the information!

- “Rockbox default theme is not very pretty” – that’s no wording I like to see in the official manual and it isn’t true. If
» you like or dislike the default theme is heavily depending on your taste, and to be honest, I really like the default wps
» on my mini.

Maybe it is just the sansa ;) I put this in because I was pretty disappointed when if first saw the sansa default wps.
I think that could be enough to turn some people off rockbox. The old section also talks about themes - but not in enough
detail to tell you how to choose a different one.

- the reworked Playlists section gets the facts wrong: Rockbox will _not_ play simply the next file in the folder,
» it will play the next file in the playlist. If you started playback from the file browser this is in fact the next file in
» the folder. If you use the database or a playlist it’s not necessarily. While this gets somewhat clarified later
» writing this way simply causes confusion.

I was walking through an example where the first file was played from the file browser. But I will think about this more,
to try and not cause confusion!

- not all players have a sleep timer. Besides, this is nothing I’d like to see in an introductory chapter.

Fair point.

Hey, I’m also glad that someone wants to work at the manual and really don’t want to discourage you, hope you can take my comment as constructive critic.

I only read the first part of what you already posted in the forums (especially the new “first contact” section). Some of the things you write in general parts, which would be used for all manuals, are not true on all players. While Rockbox tries to be the same on all devices it simply can’t be because of hardware limitations. E.g. the currently supported Archos targets use a chip to decode the music and would never be able to play ogg vorbis or aac, also “dual booting” is currently not possible on all players (for example not officially on the Iaudios) or on the Archos’ it’s done differently (you load the official firmware if you want to from a running rockbox), I wouldn’t call that “dual booting”.

I think you change too much at once with this patch - it’s really hard to follow which information got added or maybe even got lost and I couldn’t grasp the idea behind it. Maybe it’s better to split it up somehow and explain why you did it this way or what you think is currently missing (like you started in the previous answer which already gave a bit of an insight). Though I also have to admit that I don’t think that especially this chapter needs such heavy changes - maybe some additions here and there but there are really other pieces of the manual that give wrong (outdated) information and it would have higher priority in my eyes if someone works on these (e.g. the text viewer paragraph).

Thanks for the comment - I will fix the format stuff, I didn’t think it was device specific.

I don’t think I’m qualified to update the more detailed parts of the manual… maybe I’m not qualified to update this bit either ;) To be honest, I didn’t want to submit a patch, just have a chat about what people thought, which is why I posted to the forum, but I was told to submit a patch, and the thread was locked so I couldn’t even explain anything!

I think the getting started section needs changing because it doesn’t really tell you how to do very much. Imagine you are coming new to rockbox, after reading that section all you will know how to do is browse files, play a file and get back to the file browser. All the other material is conceptual, and I was left at the end not knowing how to get to themes, get started with playlists etc. It doesn’t even tell you how to get a context menu up!

I thought a better approach was to get people started by showing them how to do a few simple things (and briefly introduce the concepts behind them) in most of the areas, then they could figure most of the other stuff out themselves, maybe dipping into the rest of the manual when they got stuck. Most people learn better by doing, so that’s why I arranged it as I did.

Of course if you expect everyone to read the manual all the way though then this is not needed, but I (for one) don’t usually do that.

Well, you should keep some things in mind:
- users switching to Rockbox usually know how their player works. Thus we can assume they know basic steps like attaching usb for syncing files. Almost all players supported by Rockbox have a UMS mode in which they work as external storage device. The only exception is the sansa atm. There is no real need to make the manual sansa-specific: it should cover Rockbox. Specific notes go to \opt{}-ed \note{}’s.
- I personally prefer explaining the idea behind Rockbox instead of showing examples – until the new main menu was added users frequently got confused by Rockbox’ ideas even at the first look. This is what the “first contact” section is intended at: how does the player look when you initially installed, and how is Rockbox conceptual different to other firmwares.
- We expect the users to read up the manual as far as needed to get the information they need for using Rockbox. Depending on the user this might differ greatly, and if you don’t have enough knowledge before starting you obviously need to read more … - writing the manual in a way that describes some example first will make users only read that example and come to the forums / irc whining because they didn’t got the idea behind Rockbox. Rockbox _has_ a different concept, and IMO users should read up on the manual until they understood it. Not requiring users to do this will only cause a bunch of additional support requests.

If you want to discuss how the manual should look like I’d suggest you to look around on IRC as that’s the place where devs (including manual writers) usually meet.

If you want to discuss how the manual should look like I’d suggest you to look around on IRC as
» that’s the place where devs (including manual writers) usually meet.

I figured I’d get a better reaction after I had actually done something than just telling people how I thought it should be… I guess I was wrong.

writing the manual in a way that describes some example first will make users only read that example and come to the
> forums / irc whining because they didn’t got the idea behind Rockbox. Rockbox _has_ a different concept, and IMO users
> should read up on the manual until they understood it. Not requiring users to do this will only cause a bunch of
> additional support requests.

I think I explained the concepts too. I guess I don’t agree people should have to wade through all the sections of the
manual just to get started, that is what the “Quick Start” chapter is for.

Anyway I have made some changes:

- Parred down the loading section the the bare minimum (answers my questions of where to put the files

 and what formats are ok - well it would if I could find a reference;)

- Moved all the no usb stuff and rebooting be to sansa specific.
- removed the not pretty comment

If anyone wants to see it (built for sansa) in html, it is here:
http://burbleland.com/tmp/rockbox-buildch3.html

   patch.v2 (11.9 KiB)