I'm a newbie: please share steps how to make a playlist (reading manual no help)

[Mikerman]

Great!  How are improvements made to the manuals?  Please see the above.  (Not sure, here, if it's like a Wiki where one simply can go on in/if a consensus needs to be reached first/how changed text is proposed/etc.  Sorry if there is an answer somewhere else--only 1/2 cup of coffee yet today; feel free to link.)

[Llorean]

It's very much like submitting a patch for Rockbox.

You edit the manual .tex file, create a patch for it using the "diff" program, and submit it on the patch tracker, ideally. You can also submit it as regular text, but this means someone else has to do the work to incorporate it, and makes it less likely to get looked at quickly.

[keuleJ]

No. Static information belongs in the Wiki. If someone wants to create a PlaylistTutorial wiki page, fine, but the Forums are for discussion. There should be a minimal amount of stickies, and they should relate directly to the forums (rules, etc).

OK, then we keep answering the same questions here... Maybe an FAQ, which can be reached from the menu on the left would be better...

[Llorean]

You mean the 'manual' link? It answers all of the most frequently asked questions...

[Febs]

No. Static information belongs in the Wiki. If someone wants to create a PlaylistTutorial wiki page, fine, but the Forums are for discussion. There should be a minimal amount of stickies, and they should relate directly to the forums (rules, etc).

OK, then we keep answering the same questions here... Maybe an FAQ, which can be reached from the menu on the left would be better...

1.  How would writing a FAQ be better than improving the manual?

2.  Why haven't you written one?

I see a lot of suggestions in this thread about what someone else should do to improve the documentation, but not a lot of follow up to actually make the improvements.

[keuleJ]

You mean the 'manual' link? It answers all of the most frequently asked questions...

Quote from your signature: "Please read the FAQs and the posts in my signature"

I actually found one in the wiki, didn't know about it: http://www.rockbox.org/twiki/bin/view/Main/RockboxFAQ

But it doesn't say too much about the actual handling of RockBox, it's more about installation etc.

[Llorean]

Maybe you missed the purpose of my response.

People keep asking the same questions. These questions are answered in the manual. You suggested writing a FAQ, and I asked why they can't use the manual.

[Mikerman]

I see a lot of suggestions in this thread about what someone else should do to improve the documentation, but not a lot of follow up to actually make the improvements.

Febs, I started looking at how to propose revisions to the manual and I must say I got intimidated by the process by which to prepare revisions using the LaTeX manual system--maybe I need to get more comfortable with it.

Also, with all due respect, the idea of going to the effort to prepare revisions such as outlined above (such as How-To examples interspersed in the manual) and to submit them and then perhaps to find out, after the work, that the ideas perhaps are not not wanted by the devs and others who decide somewhat cools the enthusiasm for going forward with such effort.  It might be beneficial to know what (if anything) might actually be desired first with the manuals.  

[Llorean]

Now wait, that's not quite fair.

The same person can't say "The manual doesn't contain enough information" AND "tell me what needs to be added."

If the person thinks the manual is insufficient, surely that same person has some idea as to what is lacking about it, right?

[Mikerman]

Actually, Llorean, if you're referring to my post, that's not what I said.

Earlier, I had suggested adding "How do it" instruction sets interspersed throughout the manual; I later referred back to that.  As far as I can tell (maybe I missed something?), no one said anything about that.  

I think what is happening here is a disconnect to "manual language"--it just seems that for some people, reading a description of how to do something does not register as easily as seeing it explained in step-by-step fashion (although the Rockbox manual often is close to that already in many areas).

Which raises a possibility that some manuals follow:

After a description of some chores that people may have found harder to grasp in the past, perhaps provide a step-by-step example, by numbered steps (which always seems to help people), along the lines provided above.

This shouldn't be a major chore and could be limited to the historically "harder"-to-grasp features, features that may tend to get ignored, or basic features with multiple steps, where one wants to make sure the audience has them down:  playlists, perhaps how to record, perhaps random album play, perhaps how to set the radio, etc.

Just a thought.

I'm happy to do so and my hunch is others are as well.  But I personally would hate to go through the effort of doing so with it being decided after that such tips/instruction sets are not appropriate for the manual.  (The idea is, decide what's wanted first and then use the efforts to reach that goal.)  

And I know I have to look at it again, but LaTeX intimidates the heck outta me--I wish it wasn't so seemingly complex.

[bunkmedal]

Sorry to resurrect an old thread here, but I happened upon this because I was searching for an answer to a question very similar to the one raised here and this thread helped me. However I see that there was some dispute/confusion over how/if the manual should be improved and nothing was changed (the manual is still the same as far as I can tell). I think there is an issue with the manual in the section on playlists which has the potential to cause confusion - it certainly did for me and I presume it was the same for the creator of this thread.

Specifically the manual states -

""Section 4.4.3.  Adding Music to Dynamic Playlists.

The Playlist Submenu allows you to put tracks into a 'dynamic playlist'. If there is no music currently playing, Rockbox will create a new dynamic playlist and put the selected track(s) into it. If there is music currently playing, Rockbox will put the selected track(s) into the current playlist.""

but how to access the playlist submenu is not described (you do this by holding in the select/navi button). This was the root of my confusion, I spent some time trawling through the manual trying to find out how to access the playlist submenu and couldn't find it - if it is there then it's not in a convenient space. All that needs to be done to solve this issue is to add a sentence to the manual describing how the playlist submenu is accessed. Something like this -

""Section 4.4.3.  Adding Music to Dynamic Playlists.

The Playlist Submenu allows you to put tracks into a 'dynamic playlist'. To access the Playlist Submenu hold down the select/navi button whilst highlighting a song. ""

I am sure adding this information would solve the issue for a sizeable portion of users.

[GodEater]

"4.1.2.  File Menu

The File Menu allows you to perform certain operations on files or folders. To access the File Menu, position the selector over a file or folder and access the context menu with Long Navi."


Picked from a random manual (the H1xx), and it even has a picture of the menu that it brings up - showing quite clearly the playlist menu.

I'm inclined to agree it would make more sense to include the button push required nearer to each section that it's required in. I'm a big fan of the old "tell 'em what you're gonna tell 'em, tell 'em, and then tell 'em what you told 'em"  

[nls]

I added a bit of info to the section about the playlist submenu, now it says that it's a submenu of the file menu and references that section.

also Re: some of the above posts, manual improvements are always welcome, we are in constant need of updating and making the manual as easy to understand as possible, if you are not sure if a change is wanted, please come into irc and ask about it.

[Chronon]

LaTeX is also pretty widely used in academic circles.  There's a wealth of information to be found on the internet.  If you want to know what a command does or need to find how to do something in LaTeX it usually doesn't take too much effort to track it down.

I am currently immersed in my own LaTeX work at the moment -- dissertation writing.  But I will certainly contribute time and attention to the manual when time becomes more abundant.

[bunkmedal]

"4.1.2.  File Menu

The File Menu allows you to perform certain operations on files or folders. To access the File Menu, position the selector over a file or folder and access the context menu with Long Navi."


Picked from a random manual (the H1xx), and it even has a picture of the menu that it brings up - showing quite clearly the playlist menu.

I'm inclined to agree it would make more sense to include the button push required nearer to each section that it's required in. I'm a big fan of the old "tell 'em what you're gonna tell 'em, tell 'em, and then tell 'em what you told 'em"  

As I said, I'm sure it was there, the problem was that it wasn't in a convenient space for people who just jump straight to the playlist section without reading any of the sections before it. It's not that people are idiots and can't take in instructions, it's just that the vast majority of people aren't going to sit down and read every section in order. After about 5 minutes looking for instructions on how to access the playlist submenu I just gave up and looked on the forum.

I think the solution carried out (referencing the previous section) should solve the problem.