[BRLTTY] Let's improve documentation for the non blind

[Dr. Volker Jaenisch]

Hi Community!

On 26.12.2014 05:40, Dave Mielke wrote:
> The other side of this issue, though, is that adding 
> that kind of extra verbage all over the place would be nothing but confusing 
> clutter to a blind user who already understands the context. 
Why can the blind people be confused by some structured information they
cannot read at all?
As I stated in the subject the information base I like to bring up is
for the non blind AND the
visual impaired people AND the people that may assist the former noticed
people BUT NOT the blind.
> So, in the end, 
> especially in this area, the blind dudes tend to win out. 
Yep. The - I call them - priviledged - blind dudes. Yeah they win.
But there are others - not so priviledged - blind and visual impaired
people out there. Maybe lots of.
And you never ever may hear of them since they are not capable to even
use brltty to communicate with you.
My Brother for instance. And he comes from a  rich and educated country
born as a son of a professor.
He is lost. Not because of his capabilities. He has perfect memory - he
knows exactly what happened at 12.14.1980 and he learns as quickly as hell.
Why he is lost has lots of reasons that are not brltty allone. But
brltty can help him - because it is all he has.
He has no jaws, no windows, only brltty. And he is stuck. -- and who is
helping him?

Me. And I am not blind. And I have to come clear with brltty. And out
there is legion of People not even understanding brltty. But they never
communicate
with you becouse the are not able to communicate with you at all.
I think our mission is to reach as most people we can - or?
> Now, perhaps, you 
> have an additional bit of empathy for how blind users feel when they encounter 
> all those graphically oriented web sites which are almost impossible for them 
> to use.
>
> As an aside: You bear the title Doctor, so, just perhaps, you've written a book 
> or two. If not, you surely have colleagues who have. Have you ensured that 
> those books have adequate and easy-to-understadn wording associated with each 
> picture so that a blind reader can make sense of it?
Rougly you state: "The non blind people do things that we blind cannot
read so why should we blind people produce
things for the non blind?" Sorry, but this argumentation sounds a bit
revanchist to me.
Should we hearing people stop producing music since there are some deaf
people on earth? Should deaf people no longer produce sounds for us
hearing people?
I am sure you find out that your argument is ridiculous.
> I dig into the config of brltty and it all is clear and straight - if
> someone knows where the keys "LeftGdf" or "LeftWheelUp"
> are located on the physical device.
>> LeftWheelUp should be easy enough to understand. There's a vertically oriented 
>> wheel at the left end of the top of the device. LeftWheelUp means rolling that 
>> wheel in the upward direction, i.e. toward the back of the device. I don't 
>> recall this ever having been a point of confusion in the past.
*There is no wheel at this device at all*. There are two rockers
(Up/down) together with a pushbutton (Press) left and right at the top
that have take over the function of the former wheel of older versions.
>
> LeftGDF is a different matter. Yes, it'd be hard to guess which key this one 
> is. I expect, though, that the documentation for the actual device does explain 
> it. For the most part, we name the keys the same way the manufacturers have.
It is completely ok to have a code internal naming convention which do
not accurately reflect changes in the design of the external world - as
long as the user documentation is according to the user/producer naming
of the buttons on the device. In case of the Focus 14 blue this is not
true. The user documentation is misleading. 
>> Also the documentation of the individual key bindings descriptions are
>> misleading:
>>
>> go up one line: LeftWheelUp
>>
>> If I read "go up one line" I imagine the cursor to go up. But in this
>> case only the reading focus goes up one line but not the cursor.
> Yes, that'd be a sighted person's perspective, but it's not a blind person's 
> perspective. Since these descriptions are meant for quick reference by a blind 
> person, it's their perspective which must be targeted.
>
> You, as a sighted person, see the whole screen, so, in a single glance, you 
> kind of know everything it says, where everything is, etc. So, where the cursor 
> is, which area has special highlighting, etc, is the most important thing you 
> want to be told about, so it's those areas that you tend to think about when 
> movement is discussed.
The different perception of the world does not change the need for a
clear terminology,
well structured documentation and fast access to the things one search.
If you do not agree on this fact we should end our discussion.

To the terminology:

You write:
go left one window

and :
go to end of line

The first operation moves the window one instance to the left.
The later moves the window to the end of the line, but no "window" is mentioned. Why not mention the "window"at the later?

To the structure and the access:
The list of operations is not structured nor even sorted.

Even the same operations that are represented by more than one key-code have definition listed 50 lines appart. E.g. 

go up one line: LeftWheelUp
...
50 lines
...
go up one line: RightRockerUp

A simple sort operation before putting out this lines would improve the readability a lot. 
And I am pretty sure that also the blind people will be happy about this.

Additional I would like to see some structure:
* Cursor Movement
* Window Movement
* Searching
* Setting Attributes
etc.