I write for a living. No, nothing fun, I write technical instructions. To wit:
Extend the left foot toward the ventral side of the body.
Extend the left foot toward the dorsal side of the body.
Repeat Step 1.
Move the foot vigorously and randomly.
That kind of stuff.
Well written technical instructions are the most easily understood writings in the world. Some of you may have to take my word on this; you may never been exposed to good technical instructions.
I write good instructions.
1.a I use the imperative voice.
1.b I do not use personal pronouns.
1.c My outlines never have more that three levels, excluding section headers.
1.d I use consistent terminology, formats, and constructions.
You get the idea.
Before I have any one try to follow my instructions, I have someone read the document, just to find gross errors. I have this person read aloud any passage they do not understand to me.
Often the problem is a typo, usually involving pronouns or prepositions.
Occasionally the reader is unfamiliar with a written word; less often the reader does not know the word.
However, frequently the reader will understand the passage after reading it aloud; the reader just does not comprehend the written instructions.
I understand that language is a verbal/aural … thingee, but I write in a phonetic alphabet, not ideograms; the transition is not that difficult.
I think we may really be entering the post-literate age.
Some people prefer the spoken word over the written word. Something about different ways of learning or thinking. Me, I prefer the written word, but sometimes I do kind of read it out loud to make sure I understand what it’s saying.
There’s also something about articulating that changes things. One thing I tell junior people in my office, when they’re writing something and hit a wall, talk it out: explain to someone verbally what it is they’re trying to accomplish or explain. Often, simply saying it out loud frees the brain up in some way that makes it make more sense.
Oh, yes. I work in a highly regulated industry, and the regulations I have to implement are brutal. Generally very well outlined, but incredibly dense (would it have killed them to use a separate sentence instead of two nested subordinate clauses?). I often need to read them aloud while touching a pencil to each word in order to understand them.
However, some intelligent and educated people seem unable to comprehend written instructions alone, while some one I believe to be significantly less intelligent not only comprehends the instructions, but finds all the syntactical errors. It’s interesting.
But, that’s why there are three stages of training.
Generally speaking, people learn in one of three modes - visual, auditory, and kinesthetic.
Visual is your medium. Some people can read and absorb information very easily that way.
Auditory is my medium. While I can muddle through written instruction, I am much better if someone will explain it to me.
Kinesthetic is my students’ medium. They have to DO to learn. Reading instructions means nothing to them. Hearing instructions isn’t much better. Following someone’s example is the only way to teach them.
(Actually, kosher regs aren’t bad. ‘They’ decide what has to be done; they tell you; you do it.)
Generally speaking, training entails three modes: written instructions, demonstration, and performance to demonstrate competence.
One would think performance of competence would be the most important element. Wrong. Documentation rules in a regulated industry.
I must have a written procedure. This written procedure must be present during the activity. In the event of an inspection, the activity must be performed exactly as described in the written procedure. This is the Ten Commandment all rolled into one.
A Luddite should be able to perform any task in my facility just by following the written procedures.
If a trainee is performing the activity according to a demonstation, I have no way of knowing if the written instructions are adequate and correct.
Programming is very similar to technical writing in that everything is about reducing a complex process into simple, clear steps for an idiot-child. And frankly I wouldn’t say that program source code nor technical writing are “the most easily understood writings in the world” as humans don’t really operate like a computer does. Of course, I don’t see why speaking the instructions aloud should make them any more clear. Personally, if anything, someone saying something as mindless and tedious as detailed instructions would turn my brain straight off and not a single word would find traction anywhere at all in my head.
But technical writing uses the normal language. Word like “operate”, “instrument”, “option”; there’s nothing like “codFld-IO”.
Source code isn’t that hard to read if the definitions are handy. (I’ve never coded in the really basic languages, though).
While I have you here, do you have any online references for software validation, or for what kind of specifications software has? I have to address that in a procedure.
I am not validating the software myself; it’s for 21 CFR 11.