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

[Dave Mielke]

[quoted lines by Dr. Volker Jaenisch on 2014/12/26 at 02:52 +0100]

>After 15 years a new braille device "Focus 14" arrived at Christmas for
>my blind brother.
>It took myself - a senior programmer - more than two days of reverse
>engineering to make the new braille display
>usable to my brother.

I hope you won't be offended by my position that software should never be 
designed with the goal that a "senior progammer" can figure it out. Software 
must only ever be designed so that users (who probably aren't programmers at 
all) can figure it out. Programmers, and especially senior ones, love to make 
assumptions that have nothing at all to do with the way users think, and that's 
the downfall of many an app.

Note that I'm not picking on you in particular, although I'm most definitely 
picking on programmers, and especially senior ones, in general. I myself have 
been programming since the early '70s, and have been a programmer (sorry, a 
"software designer") by profession since 1978. So, if you're a "senior 
programmer", I then guess I'm an ancient, or perhaps even an antiquated one.

This kind of discussion reminds me of when I'd go into the bank (in those 
ancient, pre bank card days) and observe the tellers explaining to myself, as 
well as to other clients, that the computer wouldn't let her do this or that. 
I'd usually interrupt them to explain that it wasn't the computer's fault. It 
really was the poor insight and/or skill of whoever programmed the tools that 
they were being forced to use because he probably had no idea regarding what a 
real live teller actually had to do, and of how easy it should be for her to do 
it. I'd encourage them to complain to their management about the rotten quality 
of computer programs that they were being given, rather than to complain about 
the inannimate pieces of hardware that could neither hear them nor resolve 
their problems.

>Why? Not because of technical problems. It's just the lack of a
>terminology and a diagram for not blind persons.

Yes, I agree with you. 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. So, in the end, 
especially in this area, the blind dudes tend to win out. 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?

>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.

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.

>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.

A blind person, on the other hand, only sees one line at a time. On a smaller 
device, e.g. the Focus 14 that we're discussing, he only actually sees a very 
small portion of that line. He has no idea where anything else is, what the 
rest of the screen says, how the screen is highlighted, etc. The most important 
thing to him is where his braille device is positioned on the screen and what 
that very small area says. It's that area, therefore, that he tends to think 
about when motion is discussed.

Consider when you're using a telescope. If someone tells you that "this button 
goes left", you don't first think that that button makes some distant point in 
space go left. Of course, you immediately understand that that button makes the 
telescope look to the left of its current position.

>Overall I miss the great picture on what is going on. There is no meta
>document that discribes the difference between cursor and reading focus
>movement and
>this crucial difference is also not reflected in the terminology of the
>config files.

But it's implicitly understood by blind users. The controls are on their 
braille devices - not on their computers - so they just understand that the 
controls impact things from the perspective of their braille devices 
themselves.

>Complaints do not make things better. I like to contribute.

Excellent!

>You may find a graphical documentation of the BRLTTY Key-Bindings to the
>physical keys on the FS Focus 14 here:
>
>https://inqbus-hosting.de/volker/focus_14_doku.odg/at_download/file

Including this sort of thing for just one model wouldn't, in and of itself, be 
all that useful. It might be extremely useful, however, were we to have such a 
picture for each and every model (or, for at least most of them). I'm 
wondering, therefore, if you might have the time to put together just such a 
collection.

It also highlights an interesting "problem". I myself - and, in fact, most of 
us - am unable to even check it out in order to aprove it for web site 
inclusion. You see, most of us (myself included) are fully blind.

>Tell me how to contribute more ..

We'd welcome whatever you may be able to contribute. As mentioned above, 
perhaps you could put together a collection of braille device pictures for us 
that would assist sighted users.

On the issue of key layouts: Some of our key tables already do contain verbal 
descriptions of them. Check out the *.ktb and *.kti files within the 
Tables/Input/*/ subdirectories of the source tree for lines which begin with 
the keyword "note". After installation, these files end up in the /etc/brltty/ 
directory. Since verbal descriptions are useful to both blind and sighted 
users, completing these descriptions is something that definitely must be done.

-- 
Dave Mielke           | 2213 Fox Crescent | The Bible is the very Word of God.
Phone: 1-613-726-0014 | Ottawa, Ontario   | http://Mielke.cc/bible/
EMail: dave at mielke.cc | Canada  K2A 1H7   | http://FamilyRadio.com/