Message from a Visual-Tactile Learner v 2.0

[Randall Sawyer]

Documentation is vital to empowering users to employ code. That is why texinfo has been developed. Obviously, whenever someone writes documentation, s/he have and audience in mind - those who will usefully make use of said documentation and employ the code it explains.

Consideration for the translation of documents from one language to another - through the services of translators - is handled vie gettext and included translation files. Thus, the potential audience is expanded.

Interface libraries and applications have been developed for users with physical visual and hearing impairment in order to access content through augmented means. Thus, the potential audience is expanded.

There are a number of us who think primarily in pictures and/or spacial forms. In terms of available documentation, we are a subset of the population which is served - or not - in a hit-or-miss fashion. As a literate English-speaking American with good hearing and vision, but with a neurology emphasizing visual and/or tactile cognition, I see myself as an apt advocate for this sub-population.

Examples:
 1) In order to comprehend it, I mentally convert algebra into geometry - or else an animation of melding products, cleaving factors, cartwheeling fractions, and the order of operations (PEMDAS) as "contained-in-a-box, glued-on, velcroed-on, touching".

2) I prefer to write code in C over some high level language such as Python or _javascript_. Why? Because, when I am writing C, I am FEELING an imagined physical structure of consecutive arrays of bytes in memory within the computer I am using. When I do write in a high level language, I mentally translate symbols into an internal sensation of the strings, arrays and objects I am employing and manipulating. Perl I handle as if doing algebra. When dealing with XML, I see distinct plastic elements snapping in and out of each other.

3) Even before learning to write code in my childhood, I always took words to be handles - stand-ins - for what they represent. Whenever I read or listen to a phrase, I immediately convert the words into a constellation of points representing the form they indicate. In real time, I mentally convert structures, attributes and relationships into words. (Because of that, whenever writing a paper, I never had to concern myself with plagiarism - since that would require greater effort.)

Let me share with you an exemplary document which serve folks like me. It is a restaurant menu - not code. I include the link only to help make my point: Mia Sen menu

I am able to read, comprehend and apply much - but not all - of what I read in code documentation. For example, the presentation of the GLib and GTK+ documentation serves me well as does that in perldoc.org and the latest HTML presentation of the GSl (http://www.gnu.org/software/gsl/doc/html/index.html).

On the other hand, for many years, I have struggled to read and comprehend much of the documentation coming out of GNU land to the point of making use of the code it describes. I want to become competent in using autoconf, make and the like. I have tried many times, eventually giving up with resignation each time. Now, I refuse to give up.

At the time of composing this email, I am pausing from painstakingly re-writing a copy of 'makeinfo' for myself with lots of 'print' commands in order to completely understand its workings. My aim is to either employ the existing parser or to write a new one which will provide me and others like me with friendlier HTML output.