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

[Dave Mielke]

[quoted lines by Dr. Volker Jaenisch on 2014/12/29 at 00:55 +0100]

>Why can the blind people be confused by some structured information they
>cannot read at all?

Because there'd need to be more than just the picture. There'd most likely need 
to be text (which blind users would see) explaining what the picture is all 
about. I'm not sure how this would all end up, but consider my reverse example 
of a document with text that explains tghe pictures so that blind users can 
"see" them. Especially when a picture is complex, there'd need to be so much 
explanatory text that I'm sure it'd be rather bothersome to sighted readers.

In HTML, for example, a simple <img> element with a short, meaningful alt= 
attribute (say, alt="[picture of Focus 14]") would be fine.

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

Yes, I understand this. And, yes, I readily acknowledge that what would be 
helpful to these people isn't something that I understand intuitively. Either 
it hasn't been much of a problem over the last (about) 20 years, or no one else 
from this group has taken the time to complain to us throughout that length of 
time. In any event, I'm always open to improvements.

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

But they don't need to use brltty to communicate with us. Perhaps what you're 
actually saying is that, without anything, they can't even find out about 
brltty. If so, this, of course, is a "catch 22" - without anything, they 
wouldn't be able to find out about brltty even if its documentation were 
perfect. So, perhaps what you're really actually saying is that they'd likely 
go to their sighted acquaintances, who might discover brltty but then find it 
difficult to figure out because they lack a blind person's perspective.

>My Brother for instance. And he comes from a  rich and educated country
>born as a son of a professor.

:-) As all of us parents know, even the best of environments doesn't 
necessarily produce the best children. This is just a general observation, of 
course - I'm in no way referring to your brother, and wouldn't want you to 
think I were. I understand what you're wanting to impart, but it's counter to 
how I myself analyze things. The brightest professors, for example, may not 
have the slightest clue regarding how to relate to their spouses, children, etc 
since IQ doesn't imply other attributes like empathy, patience, the ability to 
listen, etc.

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

Yes, I understand. And, regardless of how my direct style of discussing any 
issue may make it appear, I really am thankful that you've taken the time to 
bring it up.

>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 don't understand why they wouldn't be able to communicate with us just 
because they can't figure out brltty. If they can't figure it out, then that 
presumes that they've found it. If they've found it, then that presumes that 
they're able, at least in some way, to use their computers. If they're able to 
use their computers, then, at least to some degree, I'd expect them to be able 
to communicate with us.

>I think our mission is to reach as most people we can - or?

Yes, I agree.

>> Now, p>> 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.

Yes, it would be if that's what I meant. I think that I should've worded that 
statement a bit differently, i.e. not making it look like a personal attack on 
your integrity. Upon later reflection, and also thanks to a private comment 
sent to me regardign that paragraph, I now regret the way I wrote it. I'm 
sorry.

My actual intention was to illustrate two things. The first was to show how 
easy it can be for one group to inadvertently ignore the needs of another group 
- in other words, to acknowledge that, yes, it's just as easy for blind people 
to ignore the needs of sighted people as it is for sighted people to ignore the 
needs of blind people. The other was, as already mentioned above, to hint at 
how too much concession, done in the wrong way, to another group of people can 
actually make things much worse for the primary audience.

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

This is something that I didn't know, and that no one has ever brought to my 
attention before now. We do have focus 14 users, but I guess they either don't 
need to refer to the bindings documentation much or they've just been making 
that transformation intuitively and didn't think they should bother us about 
it.

The fact is, though, that we really do want our key names to reflect what's 
actually on the devices. This Focus 14 issue will need to be corrected. Are the 
two press buttons immediately behind their respective rockers? since there are 
already a couple of rockers on the front, I guess we'll have to come up with 
more specific terminology.

Does the Focus 14 documentation still call them GDF keys? If not, what are they 
called now? We can fix that, too.

One of our problems, by the way, is the cost of braille devices. There's no way 
that we can afford to set up a lab containing all of the vauious models. What 
this ultimately means is that we find ourselves often implementing support for 
devices that we've never actually gotten our hands on. And, of course, being 
blind, we can't even look for pictures of them, either.

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

Yes, I get it. This, as mentioned above, hadn't previously been brought to our 
attention, and we won't likely be fixing a problem we don't know about.

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

Yes, I agree. There are limitations, though. Clear terminology is subjective, 
and going overboard to have fully objectively clear terminology can, and often 
does, push away non-technical people. Well-structured documenation is a nice 
goal, but personal time to work on such things is often preempted by the more 
urgent needs to fix functional problems, to support new devices, etc. There's 
also the unfortunate truism that, for a software person, working on software is 
far more stimulating than working on documentation. We're not a big company, 
but, as available time in our personal lives permits, we do what we can.

>If you do not agree on this fact we should end our discussion.

I don't respond well to threats, so I won't respond to this one except to say 
that that decision is yours, and yours alone. I promise you that I won't pursue 
you if you disappear.

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

No, you've misunderstood. You've loooked at the wording, and then rephrased it 
according to your idea of proper terminology. The phrase "one window" refers to 
the amount of the move. I assure you that if we were to rewrite that to say 
"one instance", very few people would understand it. The term "instance" is a 
very highly technical one, and our primary audience is "real" people.

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

Yes, of course. This is a very good suggestion. There's a problem, though. The 
"simple sort" would require doing somethign extremely ineligant to the code (a 
poor excuse, I know, but easily maintainable code is also a prime requirement). 
Ideally, we'd reorder our enum of commands to make the sorting straight 
forward. The problem is that the values of that enum are exported to an API, so 
they can't change. I'll need to figure out a way to do this which wouldn't 
require a full duplication of every single value.

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

Yes, I agree.

>Mh. My brother may not have this inbuild implicit insight you attest all
>blind users. :-)

Perhaps not. But, then, I can think of lots of people who wouldn't readily 
understand what "moving by an instance" means, either.

>Without my help he had never mastered the focus 14 brltty keybindings.
>He is very intelligent - has an absolute memory -- he never forget
>anything - and learns at a speed of light.

He's far better than I am, then. I can't even remember what I ate for lunch and 
supper yesterday. I can at least remember one truly important thing - that the 
Bible is the only source of truth.

>But without knowing the names of the buttons all the documentation of
>the keybindings is useless.

Yes, but, as discussed above, we, very unknowingly, have a Focus 14 key naming 
problem. It is, therefore, currently "useless" by accident, by ignorance, or 
whatever you want to call it. We don't like this situation any more than you 
do. Please try to be a little forgiving with respect to this particular issue.

>It was not possible even for his genius to fiddle it out by try and fail.

But lots of others apparently can - and have - so I guess each person has his 
own set of genius-like skills. One person doesn't have them all, and none of us 
sets the standard for anyone else.

>I would be honored to craft this graphical documentation for the community.

We'd better first discuss what we mean by graphical documentation. Are you now 
thinking of more than just helpful pictures of the various models? If so, what?

I'm reluctant to add a lot that we ourselves can't audit. Adding pictures is 
fine, as long as they have a standard format, standardized content, meaningful 
file names, etc.

A brief comment on meaningful file names: The one you sent me was just named 
"file". If I forget what's in it - and, as already mentioned, I'm quite able to 
forget things, primarily because I'm a flawed human being - I may lose track of 
it. Also, I don't even know what format it's in, other than the fact that a 
tool I have says that it's in Open Document Drawing format. Without serious 
research (which I don't feel like doing), I don't even know what the correct 
file extension for such a thing is.

Now, I'm going to ask a direct, personal question: If you think, qutie 
correctly, that our terminology should be clear, then why, I find myself asking 
myself, would you send me a file that I can't even look into that's just named 
"file"? You want me to trust your work, and, in spite of this, I think I can, 
but surely you must understand that doing such a thing does make your work look 
sloppy.

>Since I do not have physical access to all the many braille device
>brltty support, I will need some help from the community.

Nor do we, and there's also no guarantee that users of all the various models 
are represented within this (mailing list) community. Really, the best way is 
probably to scour the manufacturers' and distributors' web sites, the 
documentation for other screen readers (JAWS, Window Eyes, etc), and other such 
potential sources of information.

We should also decide on a standard image format, and my guess is that Open 
Document Drawing format isn't it. For example, what we may find ourselves 
needing in many cases is for a user to simply take a picture of his device. We 
also need to consider that we may need multiple pictures (top, front, side) for 
at least some of the devices.

>Here is my plan:

We work rather informally, here, as we all have other commitments, private 
lives, etc, too. While we'll probably never reach perfection, what we do here 
is to slowly and gently iterate as best we can toward making things better.

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