Rockbox

Tasklist

FS#5999 - Misleading description for Navi button (H1xx series)

Attached to Project: Rockbox
Opened by Joaquim Dias (dunno) - Friday, 15 September 2006, 16:03 GMT
Task Type Bugs
Category Manual
Status Closed
Assigned To No-one
Operating System Iriver H100 series
Severity Low
Priority Normal
Reported Version
Due in Version Undecided
Due Date Undecided
Percent Complete 100%
Votes 0
Private No

Details

In section 3.1.1 at the end of the last paragraph you describe the joystick as Navi and describe its function,

Quote

"Pressing the joystick down is labelled Navi throughout this manual"

End quote

This to me implies that anytime I see the word "Navi" I must press the joystick down, pretty obvious and clear except when you see the follwing navigating instruction in section,

5.2. Navigating the Main Menu

Navi/Right

This to me means press and hold the joystick down AND move the joystick to the right, I dont think thats the correct instruction, it should be "Joystick right", or for the H1xx's relable the "Navi" button to "Joystick" and refer to a Joystick press as "Navi".
This task depends upon

Closed by  Dominik Riebeling (bluebrother)
Friday, 22 September 2006, 07:29 GMT
Reason for closing:  Rejected
Additional comments about closing:  Useless discussion.
The reporter finds something misleading that is commonly used and proper english. Also, his \"replacement\" proposal would break the text heavily.
Comment by Jonas Häggqvist (rasher) - Friday, 15 September 2006, 19:05 GMT
Since when did a slash start meaning "and"? So how do you read "I need to buy an apple/orange"?

Navi/Right means "Press Navi, or press right" which is completely correct.

Navi does mean press down the joystick.
Comment by Joaquim Dias (dunno) - Friday, 15 September 2006, 19:57 GMT
Since when did a slash start meaning "and"? So how do you read "I need to buy an apple/orange"?

since when is the world designed according to you,

Navi/Right can easily be misunderstood as press down and move right.

and be more civil with your tone please.....whippersnapper
Comment by Jonas Häggqvist (rasher) - Saturday, 16 September 2006, 03:09 GMT
>since when is the world designed according to you,
>Navi/Right can easily be misunderstood as press down and move right.

I'm sorry, but you seem to be the one who thinks that the world is designed according to you:

>This to me means press and hold the joystick down AND move the joystick to the right

Most of world's (western world anyway) population would disagree. Every language I know of (admittedly only English, German and Danish, but that should do) uses / as an indicator for exclusive or. Navi/Right simply means "Navi or Right". Navi+right means "Navi AND right".
Comment by Joaquim Dias (dunno) - Saturday, 16 September 2006, 06:54 GMT
bacob_boy wrote, Quote:
Most of world's (western world anyway) population would disagree. Every language I know of (admittedly only English, German and Danish, but that should do) uses / as an indicator for exclusive or. Navi/Right simply means "Navi or Right". Navi+right means "Navi AND right".
End Quote:

Well, my mistake then, there's obviously no room for misunderstanding by using "/" as a designator/divider/taskseperator...

Comment by Jonas Häggqvist (rasher) - Saturday, 16 September 2006, 07:26 GMT
> Well, my mistake then, there's obviously no room for misunderstanding by using "/" as a designator/divider/taskseperator...

If there is, you haven't made your case very well yet in my opinion.

How can a "/" be understanded as "and"?
Comment by Dominik Riebeling (bluebrother) - Saturday, 16 September 2006, 08:48 GMT
dunno, please use quotation marks when quoting. Usually the > sign is used for that. Putting quotes in your comments without marking them makes it awful to read.

Also, I completely agree with Jonas -- when reading a / separated task (buy apples / buy oranges) you're going to do both tasks at the same time? Really? Even when you understand it as "buy apples AND buy oranges" you understand it as "buy apples AND THEN buy oranges". When trying to use Navi / Right after another you will see the difference (or equality), so this should make the meaning of that expression absolutely clear. Considering a / as "both at the same time" is plainly wrong, especially when using it as "taskseparator" (Click "File/Save as" -- is there a way to do this simultaneously?).

I can't follow your argumentation and think it's simply useless. I'm about to close this task as if you don't understand a text the way it is written we won't adjust our text to reflect your _intended_ understanding. Instead, we will keep writing it like the language is designed. And from the way the language is used (and understood by nearly of all readers) the text is correct in the way it is written. 99.99% of the users seem to understand this correctly. Period.
Comment by Joaquim Dias (dunno) - Saturday, 16 September 2006, 11:35 GMT
just two different ways of interpreting a "/", to you it implies "Then", to me it could mean "then" or "and then", but thats just me.

perhaps a description could be added to that paragraph above 3.1.2, indicating that a "/" implies "Then". *shrugs again*
Comment by Daniel Stenberg (bagder) - Saturday, 16 September 2006, 11:39 GMT
"/" implies logical OR
Comment by Joaquim Dias (dunno) - Saturday, 16 September 2006, 12:10 GMT
>"/" implies logical OR

well then the instruction Navi/Right could mean

Navi "Then" Right
Navi "And" Right
Navi "And Then" Right
Navi "OR" Right

:->
Comment by Linus Nielsen Feltzing (linusnielsen) - Saturday, 16 September 2006, 17:02 GMT
I agree with Joaquim here. Even if the "/" is to be interpreted as "or", it is still not obvious in this case. I think it wouldn't hurt to write "or" instead to avoid confusion.

Also, we actually do write "or" on several places in the manual, so how is the user to know that "/" means the same thing?
Comment by Linus Nielsen Feltzing (linusnielsen) - Saturday, 16 September 2006, 17:05 GMT
BTW, I also agree about using a more civil tone.
Comment by Dominik Riebeling (bluebrother) - Saturday, 16 September 2006, 18:01 GMT
While I agree that we should be more consistent I still don't see why this should be confusing. It is common practice to separate alternative values using a "/", and as we're writing for a technical product (software) I think it is legitimate to assume at least a bit of technical understanding. Of course we could change that to using "or", but how should a line like

Up / Down / Left / Right - Move the cursor

read then? In this case the "/" has a meaning of "and" in the sense that those keys all move the cursor (and implies the directions, which I think is understandable to everyone). Also it means "or" in the sense that you have to press one of those keys (to get one of the implied directions). And it hast these two meanings at the same time, requiring the reader to make the distinction of this fact himself. Writing

Up or Down or Left or Right - Move the cursor

would be wrong, as all keys are actually moving the cursor. Writing "and" could (in the line of the arguing stated in the original post) understood as "press all 4 keys at once". While this is technical impossible it is still a possible confusion.

So how should this be done? There is _always_ a chance of confusion.
Comment by Joaquim Dias (dunno) - Saturday, 16 September 2006, 19:20 GMT
would it really be difficult/impossible to change something as small a "Navi/Right" to "Navi or Right", or "Navi then Right" I don'tunderstand why you are so steadfast/against changing/amending the manual, and as Linus has already pointed/illustrated/remarked, there are other inconsistences/irregularities in the manual.

It's good practice to keep consistent operandors thrughout the manual, which obviates confusion which may arise due to differing operandors.

Dominik, I really dont understand your reluctance to compromise on this.
Comment by Jonas Häggqvist (rasher) - Saturday, 16 September 2006, 19:39 GMT
I agree that consistency is important, but I'd rather see "Navi/Right" used than "Navi or Right". The reason is that it seems more concise and looks nicer to me than "or" - especially for longer lists.

I have not tested this, but I would imagine it is in fact also better for people reading the manual using TTS. ("right slash left slash up slash down" vs "right left up or down").
Comment by Joaquim Dias (dunno) - Sunday, 17 September 2006, 10:22 GMT
Dominik and Jonas, the impression I have of the two of you is that you are very proffessional AND Pedantic, whilst you are eager to point out that I'm wrong with my proposal I feel obliged to point out the MANY inconsistencies of operandors within the manual you are so relcutant to change but yet the defiencies are glaring. I'm not too concerned about "or" instead of "/", but please do try to keep the existing operandors consistant, also the spacing around operandors should be consistant, some instructions are just plain wrong, e.g. "hit play", or "press Navi".

ALL quotes below are from the online manual, (my comments in brackets)

> In the tree view use Down and Up to move around the selection. ( use of "and" not "+", or vis versa )
> Use Navi or Right to select an item, (use of "or" instead of "/" ).
> In list views you can go back one step with Left or Stop, ( "or" )
> Play+Up/Down, ("/")
> Navi or Right, ("or")
> deleting a file. Press Navi, (must a user press the joystick twice ? )
> press Right to load the chosen theme and apply it, (must a user press the joystick twice ? )
> Left, Right (a third operandor is introduced for "or",a "," )
> Up, Down, ("," and spacing )
> Press Navi to go to the preset list, (implies press twice)
> Up / Down, (nice spacing and easily readible)
> Hold Play and press Left — Sets Start Point (A), ( implies select "Hold" select "Play", press left?, what do you mean ? )
> Hold Play and press Right — Sets End Point (B) , ( Press and hold Play and select Right, far more descriptive and correct).

> Play+Right/ Left, ( no space before "/", it looks much worse in the manual ).
> Yes and Ask, ("and", which is it "+" or "and" )
> Left, Right, Up and Down, ( use of "," instead of "/" )
> Up/Down/Left/Right
> Left, Right, Up and Down
> Up, Down, Left, Right
> Left/ Right, (no space before "/" makes it diffiuclt to read )
> Navi/Play, ( no spacing at all around "/" looks awful in the manual)
> Left / Right, (nice spacing)
> Press Navi to pause the game. Press Navi again to resume the game. (again, press navi implies press joystick twice )
> hit Stop, (surely press is more precise and descriptive )
> hit Play, (hit !!!, ok I'll hit it hard )
> Up / Down
> UpDown (no operandor at all )
RightLeft (no operandor at all )
Up / Down / Left / Right, ( nice spacing )
Comment by Joaquim Dias (dunno) - Sunday, 17 September 2006, 13:21 GMT
The above is with reference to the H1xx series player which has a joystick
Comment by Jonas Häggqvist (rasher) - Sunday, 17 September 2006, 16:16 GMT
I'm certainly not opposed to being consistant. In fact, as you point out, I'm quite pedantic when I get in that mood, so fixing these inconsistencies would be right up my alley and I certainly appreciate that you've taken the time to find them.

I'll probably not have time to do it myself, but I suggest the following style:

Use "press" - not "hit", "click" or anything else.

Use " / " to seperate alternative buttons (I agree that the space makes it look nicer, while probably not typographically correct) - not "or", "," or anything else.

Use "+" to indicate a button-combination - not "and", "&" or anything else.
Comment by Martin Arver (tucoz) - Sunday, 17 September 2006, 18:56 GMT
I like that we get feedback on the manual. This means that people read it, and actually care about the quality of the manual. Now, I would certainly be more than happy if there is consistency throughout the entire manual. Problem is that there is too little time, and as you may have noticed, the manual is starting to be a pretty massive piece of paper.
Regarding the button-presses. There is now a mixture of notations, which is in part because some tables use the Action codes (which is a recent invention that will simplify all button handling for the current and new targets, even for the manual), and in part because we have never really settled on a certain style. The task to get where we are to day (manual-wise), has simply been too time-consuming on its own and has unfortunately lead to a lack of consistency.
If I could say, "abrakadabra - make the manual consistent", I would be very happy. However, if we were given patches, like a "manual_keytable_consistency.patch" we would not be far from that.
In case you want to join in on the manual writing, please do. To transfer the current tables to the Action codes is one thing that will make the button tables look nice and consistent, and something that has to be done, now or whenever someone is up for it.

(dunno, I noticed you listed some errors/typos in a post in this thread. Please edit the manual and make a patch with those changes. Then we will get closer to what you want.)
Comment by Dominik Riebeling (bluebrother) - Sunday, 17 September 2006, 20:23 GMT
Joaquim,

> Dominik, I really dont understand your reluctance to compromise on this.
I'm absolutely not in reluctance of a compromise, but I haven't seen a compromise but only you insisting on your idea most of the time. Which isn't a compromise at all.

I'm really for consistency, but I refuse to make a change to some "solution" that is also broken and needs to get revised later on again. I already gave you an example where simply replacing "/" with "or" makes nonsense. Unfortunately you haven't commented on that, so I don't have any idea how this should look like in your opinion.

Also, it seems as you're not aware of the manual internals itself. I looked for the occurrences of "or" in the discussed meaning and found exactly one occurrence. All others got introduces with the button action scheme we're currently trying to introduce. While this will make a lot cleaner and easier (from the source's view, which also means it increases consistency) we also need to consider that when thinking about the delimiter problem. Currently the action macros use "or" for which I don't know the reason, but, to be consistent, they should indeed use the same delimiter.

Furthermore, from your quotes I can't see from which context you extracted them. Writing "Up / Down" in a table is perfectly ok and should be clear at least to every person who is used to computers and the language used. This mostly applies to paragraphs, but this could indeed get explained as it may look a bit weird in the first place. As we want to use the same macros inside of paragraphs and tables we need something that fits both. I was thinking of that and it seemed that using a comma would be at least a better solution than using "or". Still, this is not good -- "Use Navi, Right to select an item" sounds even more like "press Navi first, then Right". So sticking to the / is the best solution that is currently known to me. Nevertheless, as I already said it could get explained in the introduction (I already tried to write something).

I agree on the use of "hit" and "click".

To some of your comments on the quotes:
>> deleting a file. Press Navi, (must a user press the joystick twice ? )
this should really be clear -- should we really consider the button name as a verb now?
>> Press Navi to go to the preset list, (implies press twice)
same as above. I really don't understand why this should imply a double press -- Navi isn't a verb, it is described as the middle button of the joystick, which is activated by pressing it down. So "press Navi" means "press the key that does Navi", and this is a press of the "middle" button of the joystick in the case of the h100. How should that middle button be described better than "press the joystick"?
>> Yes and Ask, ("and", which is it "+" or "and" )
Yes isn't a button at all. Ask isn't too. Maybe you want to give me the context? Referring to buttons in this line doesn't make sense at all, neither "Yes" nor "Ask" got introduces as buttons. This sounds like from a setting option, but that is totally off topic.
>> Hold Play and press Left — Sets Start Point (A), ( implies select "Hold" select "Play", press left?, what do you mean ? )
You press the Play button, hold it pressed and press Left. The hold switch (on h100 it is a switch!) is only described in a small section and its use is for disabling the keys. This is a commonly function, so everyone who uses a DAP should be aware of that. "Hold Play" doesn't refer to "Hold" and "Play" -- it even isn't separated by "+", "/" or any other of the mentioned separators. Now space gets also a separator? Sorry, but this is ridiculous.

It would be really more productive if you actually read the text and not pick some lines without any context and start adding "I don't understand this" comments on sentences that are completely correct english. I get more and more the impression that you either want to make yourself ridiculous or piss of the guys writing on the manual. And I'm starting to get pissed!

Finally, you should be aware of the fact that quite some people are writing on the manual. I'm always for consistency and tried quite a few things to achieve this but it always takes some time until all get used to it. Don't forget the manual is still a draft and we're working on quite some issues. I think it is really more important to have the description of rockbox itself correct. If you want to help out with inconsistency issues please get the manual source and start working on it. It simply is a pretty elaborate task and there is lots of other work to do.
Comment by Joaquim Dias (dunno) - Sunday, 17 September 2006, 21:06 GMT
Dominik,

>> deleting a file. Press Navi, (must a user press the joystick twice ? )

the H1xx has a joystick, the function of which is described in the manual as..
Quote

"Pressing the joystick down is labelled Navi throughout this manual"

End quote

note that in the manual Navi describes BOTH the "joystick" and a "Action"
so, one last time does "press Navi" make sense.

but really I feel I'm banging my head against a wall here, please close this thread.

Case closed, as I tell my pupils :)
Comment by Martin Arver (tucoz) - Sunday, 17 September 2006, 21:17 GMT
Dunno,
this is nitpicking. But, I get your point and we might have to improve that sentence. Leftright (iirc) from irc also pointed this out.
Problem is: no one has cared so much as to tell us what we should write instead. In my mind, the current sentence is hard to misunderstand,
given the fact that the Navi action is pointed out in the image of the iriver. If you come up with anything, let us know :)
Comment by Dominik Riebeling (bluebrother) - Sunday, 17 September 2006, 21:23 GMT
You noticed that section is marked as especially for the blind people, who can't see the above image that directly names the keys? Every "usual" user will look at the image first, which should make this completely clear in case there is confusion.
Also, I don't get the point you're trying to make. The manual nowhere describes "Navi" as being the joystick but the press on the "center" key of the joystick as "Navi". So "press Navi" is absolutely correct -- it means pressing that "center" key.
I really have the impression you don't want to understand this senctence correctly. If this is the case then I can't help you at all, even if I would start rewriting the complete manual. Reminds me a bit of that forum discussion by a guy with the nickname "dunno", so I assume this was you. At the end of the discussion (about delays of keypresses) he stated something completely different than at the beginning, making that discussion a complete waste of time that could used otherwise better -- like fixing bugs in rockbox or working on the manual.

Anyway, feel free to submit a better written text on that issue.

Loading...