Redocumenting:

     MAAS

the five-fold way

If I may be so bold, let me wax eloquent, for a moment, about the purposes of communication. These were communicated to me by my father, a Navy CIC Watch officer whose entire success and existence depended on clear, concise communication.

Once, while exiting a compartment with fellow officers, he commented on a small sign over the light switch, which read:

"Please extinguish all sources of illumination before vacating the premises."

He commented on how much more useful (and economical) it would be to simply say, "Turn out the lights when you leave." After retiring from the Navy, this observation led him to take up teaching clear communication at community colleges, churches, high schools, special events, beer halls, and even (as I once witnessed) the occasional restroom. It was his passion.

He functioned from the "twenty questions" perspective, a game we played endlessly; that is, you must figure out the fewest number of questions it takes to tease out the complete meaning of something, and then remember those questions. He was incredibly good at it.

what i learned

My father insisted that there were only five types of communication: teaching, demonstrating, explaining, persuading, and providing correct, timely, contextual facts. Remembering that he's a lifelong Naval officer, here are his five favorite examples:

  • Teaching: "You have to hold the bottom of your zipper when you try to close your fly."
  • Demonstrating: "First, grasp the bottom of the zipper; second, separate the zipper from the slide at a 90-degree angle; third, pull upward firmly; fourth, collapse the zipper onto the top of the slide and push to lock it."
  • Explaining: "In fact, a zipper is technically called an Interlocking Slide Fastener, and understanding how it works will help you get the zipper back on when you pull it too far and it comes off the end of the slide. Let me explain...."
  • Persuading: "You know, people won't think you're cool if you don't keep your fly up. In fact, they'll probably think you're stupid or something. I mean, what do you think of people that walk around with their fly down?"
  • Providing concise, contextual, timely facts: "Your fly is down."

Arguing, no matter how violent or profane, is considered a form of persuasion, although usually an unsuccessful one. Likewise, giving commands -- they don't have to obey you, even if they're supposed to do so. I think this last observation contributed much to his success as a well-liked and well-respected officer.

He included greetings as an oblique form of explaining, in that there were expected responses that "explained" where the relationship stood.

Diátaxis shouldn't have been a surprise

In light of my upbringing, it shouldn't have come as a surprise that the author(s) of the Diátaxis framework have presented something similar. They go into much more (and better) detail than my recollections. In the context of documentation, it also makes sense that they don't cover persuasion: doc really isn't supposed to handle that job. Unfortunately, it does, but that's a different argument... er ...persuasion.

And for technical authors, the framework given there conforms to a statement attributed to Oliver Wendell Holmes: "Every now and then a man's mind is stretched by a new idea or sensation, and never shrinks back to its former dimensions." That's how it was for me, at least.

So here, I have endeavored to present not a re-hashing of their ideas (there's no need, their solution is "Turing complete"). Instead, I'm going to try and write documentation on difficult subjects, using their framework and my dad's clear communication teaching, and see what may be of use.