As part of my information gathering for a set of features in a project, the development lead gave me a document he had written up containing conceptual information. It wasn’t information that we expected I would pass on to the users in the documentation; rather, he thought it was important for me to understand those concepts to fully understand the functionality. The document was mostly a discussion of some edge cases that were not covered in the design and would probably have to be accounted for in the code later so that the app would handle those cases gracefully.

I had heard that this dev lead is also enjoys writing, and it was apparent in the document. From one standpoint, it was well written. However, I had to read the document two or three times to understand what it was saying, which is one reason technical communicators exist. It was a situation I encountered a few times as a writing tutor in college: Someone brought in a paper like a master’s thesis (fortunately, I didn’t have those often), and while it talked about something I didn’t understand, I could still see that the English was structured correctly. In master’s theses, though, the audience is a specialized one, so the writer isn’t going to bother explaining every basic concept.

However, with this dev lead’s document, it was problematic that I knew the English was well structured but still couldn’t grasp what it was talking about until I read it over multiple times. This highlighted for me the difference between grammatical English and clear English. Grammar is important because it forms a foundation for clarity. But an objective for technical communicators is to reach beyond the grammatical and achieve clarity.

The following is grammatical: “A sea monkey garbles blue enterprises, but it strangles rocks rarely.” But it makes no sense.

People may confuse me with a hard-core grammarian based on some of my posts. I don’t advocate for grammatical rules for the rules’ sake. It probably has to do with my general philosophy that without rules, we have disorder and anarchy, so everyone benefits from rules. (Proponents of structured authoring would probably find this same argument appealing.) My opinion about grammatical rules is that they give us something in common based on which we communicate with each other. Those who thoroughly understand the rules can then break them with style and flair.

A cartoon I did with an article for the USU Writing Center newsletter. The article's point was that grammar isn't a destructive monster.

I would be first to acknowledge that when it comes to tech comm, as the developer’s document demonstrated, adhering to proper grammatical structures isn’t the end-all of communication. Grammar is a foundational principle, but I would say that any type of professional communicator knows (or should know) how to analyze the audience and then determine what is needed in order to bring a specific effect to that audience.

The saying has gone around that “content is king,” and as a corollary, I would say clarity is the king’s crown, scepter, and robe—everything that signifies his right to be where he is. In tech comm, content has no place if it doesn’t get the message across.

I get disappointed sometimes when I write something, and then, upon rereading it, am forced to admit that it just doesn’t make sense. So I make it better. Satisfaction replaces disappointment when I rewrite something so that it makes me say “Ah, I get it” instead of “Say what??” Because when your own writing confuses you, then it’s time to break out the red pen.

Related entries (auto-generated):

A Thought on Clarity

How to Give Effective Feedback to Writers

A Cloudy Forecast for Technical—and Any—Communication?

First Principles of Technical Writing

Important Players in the Content Review Game