Documentation theory

The following is taken from an email to a friend. It is an attempt to describe a theory of documentation I am obsessed with. Of the people I've told this to, I've gotten reactions ranging from 'it won't work', to 'it's not necessary', to embarassed silence, to 'do you want to go for a bike ride?'*

======================================================

I learn things slowly, you learn things quickly. I am coming to believe that explanations could be offered to me (and those like me) which would lead to understanding more efficiently than what is currently available.

When you are thinking about a question or problem, you close your eyes. My guess is that you are doing a transformation to a visual version of the problem domain. The math savant describes his recitation of PI as traveling through a land of numbers, he LOOKS at them.

The traditional linear narrative explanation of concepts assumes that the reader is, in real time, creating the images required to grok the meanings and relationships of the words.

I don't do that, it takes MUCH repetition before the understanding produces an image of the domain. I suspect that others have a similar cognitive process. I guess that involves the visual vs oral learning style stuff I've read about - "I see what you mean"

I see stuff that's already there, I'm not good at creating it in my head from descriptions. You are.

I think the words can be taken from the symbolic realm of the linear narrative and located in space, on a page.

An example would be producing a printed page which explained how a method call worked. On the page would be the pertinent parameter definitions, the lines which called subroutines, the lines which returned values etc. The connectors between the text pullouts would be annotated. The pullouts from the pertinent config files would be on the page.

The text is an image of words, arranged in a way which reflects the symbolic usage of them. A nudge in the direction of what I think is required to understand at a level to make use of the concepts.

I think it applies to lots of things, and has a simple basis, and can be codified: I want Python code to convert text files to SVG elements. The text becomes graphic, you can shrink, color, pull quote, change it's opacity, rotate it, and POSITION IT. My theory is that you (and folks like you) are able to _position_ concepts in order to understand them. And the framework easily accommodates standard images as well as images of words.

And of course, this is all automatable, once the tools are in place, the computer is taught how to do the pulling and arranging of the constituents of a concept.

This is something I'd love to talk about with you.


* joke reference::

Q How many ADD kids does it take to change a lightbulb?

A Do you want to go for a bike ride?