Of course, a vendor’s cross platform RESTful paradigm optimization isn’t worth much if no one knows what the heck it is. No matter how well a vendor’s phonemes follow industry trends they aren’t impressive if they don’t convey meaning.

If you don’t know what RESTful paradigm optimization is, fret not. I wrote the phrase and I have no idea. It’s buzz-poetry. It doesn’t mean anything.

Buzzwords are great, used properly. When a doctor talks about myocardial infarctions to his colleagues, he’s working out ramifications and health mandates no more than vaguely apparent to the rest of us, using specific terminology for effective communication with his peers.

Among my fellow sail enthusiasts I can rattle on about cunninghams and vangs and bobstays without worry of misunderstanding. That’s where buzzwords help. When a buzzword has mutually recognized and specific meaning, it grants accuracy to discussion.

Failing shared understanding, break out the croutons. Word salad is served.

Great examples of how to build mutual understanding between writer and reader can be found in the Mellel user guide.

Mellel is a wonderful niche word processor for the Mac. It features unique concepts alien to the Word-bound writer.

Where Word uses heading styles to define table of contents entries, Mellel uses styles for nothing more than appearance.

Auto-titles create Mellel table of contents entries, not mere styles. Without good documentation you would never know what auto-titles are or how they exceed the power of styles.

Mellel and its documentation offer two shades of brilliance. Mellel’s features are inventive, and Mellel’s English language documentation is deliberately clear. That’s impressive considering the author’s native tongue is Hebrew.

Every section explaining functionality follows a pattern. The first topic in the section on auto-titles is “What are auto-titles?”

The section on notes starts with “What are notes?”

Descriptions of lists, tables, images, text boxes, hyperlinks, line numbering, breaks, and others all start with “What are” explanations.

Nothing is left to the user’s imagination. The section on character formatting? Yep, starts with “What are characters?”

In a word processor supporting both right to left and left to right languages, the nature of character encoding is an important topic.

This paradigm is worth remembering. Call it define and conquer. Describe a facet of a system, then explain its use. A simple rule. Meaning suffers if you violate it.

Buzzwords are helpful, but there are prerequisites. The writer must know his audience and the context of his document. Ask me about points and I’ll tell you all about vintage internal combustion ignition systems. Ask a medieval knight about points and he’ll tell you about the laces holding up his socks. Seriously. They called them points. I have no idea if they had fashion accessories called condensers or spark plugs to go with their points, but it wouldn’t surprise me.

Buzzwords mutate, clarity doesn’t.

I appreciate your visit! If I can be of any help, either for technical writing or development, drop me a line. The Get in Touch! link at the top of this page is handy, or you can email me at carl@carlhaddick.com.

Samples of my technical writing are bundled with each Python example on this site. Just follow a Python article to its bitter end and there will be a link to a zip file containing both source and PDF documentation.

And bitter end? That’s a sailing buzzword from long before the term “buzzword” was in use. The end of a line or rope is properly called the bitter end, because it’s what you could hitch to a bitt, which is a kind of cleat.

See what I did there? Without context, you might think a bitter end is terrible fate at work!