The 7 Cs of technical writing

Correct before anything else

Before anything else, excellent content is true to the system it documents. It’s the most important of the Cs, so I’ll repeat it: the content must be correct, before anything else.

At this point you might asking, Should content be correct before anything else? My answer: Good question, you’re almost there. But no, excellent content should not be correct. It must be correct. It’s so obvious why correct is the most important C that I won’t explain why. Well, maybe a little: Excellent content extinguishes fires, incorrect content burns users.

Correct includes honest. This is a contentious one with product teams. They often don’t like it when I document the bugs, the edge cases big enough to park a bus, or even the limitations.

I get their need to spin it as a business decision. The way I spin it is to remind them that it’s the nature of the universe that the system can never solve all of a user’s problems. Excellent content is up front about that, treating the user with respect. Who doesn’t want to respect users?

Also contentious, I’ll go a step further: correct sometimes means shipping doc with gaps big enough to park a bus. If it isn’t correct yet, it’ll have to wait until it’s correct.

Actually, I’ve seen otherwise excellent content with an explicit disclaimer about its inaccuracy. That seems unfair to end users though. Or maybe it’s actually honest. Huh, a 7 Cs paradox?

This is the most tedious of the Cs. A tech writer has to ask stupid questions, suspect everyone’s answers, get fingers dirty, be the squeaky wheel, kick, bite, and scratch to get to the truth. There’s a lot of double-checking. Get numbers right. Get steps in the right order. Get descriptions precise. Get concepts accurate. Get a tech review. Get a SME review.

Correct means validating the content against the system. A tech writer usually ends up with only a somewhat-working system. A system in development is a moving target. The tech writer is usually the last to know when developers and product owners change things. I mitigate this by building relationships with other teams and embedding myself in their processes. I get friendly with the QA team, scrum master, and project manager. I’ve promised a lot of beer and coffee in my career.

Clear

Correct content depends on clarity. The system doesn’t always follow a straight path, but excellent content clears the fog and marks the path for users. Clear content answers the 5 Ws: Who or what does this? When and where does it happen? Why does it need to be done?

This is straight-up writing fundamentals that a tech writer learns in school. All communicators, tech or not, writers or otherwise, practice this. Language should be plain and unambiguous. Ambiguity is bad, real bad, almost as bad as incorrect content. Unclear content fuels frustration. The muddier the content, the more users have to read, the more fuel gets poured onto that fire.

Sometimes text won’t cut it. Text is linear, tabular, or hierarchical, and that’s great. But images and videos show interacting parts and more than 2 dimensions.

Concise

Overly-long content means my users have to dig through a coal mine to find a diamond.

Conciseness is like Santa Claus. Excellent content gives a big shiny diamond, not lumps of coal. The time I take to shorten my content is time I save my users.

Again, conciseness is part of the fundamental of tech writing. And that’s all I have to say about this. Happy holidays!

Consistent

Emerson forgot an exception: Consistency is a necessary ingredient for excellent content.

Consistency is about words, terminology, and appearance. When your user uses your content, don’t require them to take the extra effort to confirm the content’s meaning. Give them content they can trust to mean the same thing always.

Consistency also helps with accessibility for users with obstacles to using your content. For example, if your content is only in, say, English, your non-English users will have fewer hoops to jump through.

The easiest way to consistency is your style guide. A doc team without a style guide is like a politician on their last term: looking busy but ineffective and about to be unemployed. Bonus: Consistent terminology gives better search results.

Excellent content also uses consistent formatting. I’m probably misunderstanding that guy that nobody understands, but the media really is the message. Styling has meaning too, as much as words.

Cohesive

Cohesive documentation makes the system look like all its parts fit together neatly even when they don’t. Excellent content builds a bridge from the user’s point of view to the system’s… let’s say “counter-intuitive eccentricities”.

At the macro, structural level, excellent doc is cohesive when:

• Ideas flow logically
• Topics, sections, and chapters are organized consistently
• Y’know, stuff like that

The biggest bang for the cohesive buck is repeating a progressive pattern. By “progression” I mean going from simple to complex. I repeat this progression at all levels of the documentation:

• Paragraph: The first sentence defines a concept. Subsequent sentences reveal more detail.
• Topic: The first paragraph introduces an idea. Subsequent paragraphs give examples, describe nuances and edge cases.
• Sections or chapters: First topic gives a conceptual overview. Subsequent topics show tasks, use cases, reference info.
• Books or volumes: First section helps beginners with rudimentary features. Subsequent sections help advanced users.

Cohesive content is modular, built from smaller, composable, manageable parts. That lets a doc team add content while minimally disturbing the rest of the content. Think of a Lego house. It’s easy to add an extra bedroom that looks like the rest of the house.

Cohesiveness needs vigilance. Day to day, cohesiveness keeps a team’s maintenance efforts manageable. But cohesiveness decays over time, mostly because the system it covers gets bigger, more complex, or just plain outdated. Like technical debt in software, paying content debt is a hard sell to management because it takes away time from developing new content.

Compassionate

I’ve saved this one for 2nd last because people find it the most surprising, but compassion is almost as important as correctness.

Like correctness includes being true to the system, excellent technical content should be true to the user. What you’re aiming for here is content that encourages users to feel engaged and even emotionally connected.

Understanding the audience, their needs, and their point of view should guide what to document and how to document it. For example, users’ technical proficiency matters. Non-technical users need tutorials to hold their hands. Highly technical users like the efficiency of reference content.

This might be the hardest to do well. Good intentions are a good start but usually inadequate.

Ideally, a tech writer practices compassion by sitting with and listening attentively to the user. That’s rarely practical though. Yet again, relationships with the tech support and customer success teams help a lot.

Sincere enthusiasm is a simple way to achieve this C. Remember that technical content communicates a special situation:

• a system that helps people
• the world hasn’t seen it before

That’s pretty exciting, right? There’s no reason to be shy about that.

Complete

This is the last C and the least of them. Really, it’s the anti-C that is absent from excellent content.

If you can check off the previous 6 Cs, you’re already a technical doc rock star (a “tock” star, or “dock” star?). Governments will proclaim holidays in your name. You’ll be offered cameos in superhero movies. Of course, content should have enough coverage for what users need. But in practice, complete is nice to have, but rarely achievable or practical. Excellent content focuses on better things to help users.

Here’s why: the 2 dimensions to this C are breadth and depth. Breadth makes sense to at least give users awareness of a feature. If they ask for more depth then I know where to spend my time for the next release. Depth is trickier. Not only does it take more time, it might be wasted time. Can anyone really guess everything that users will do with the system?

Of course, sometimes I have to ship pretty wide breadth and full depth, like for regulatory compliance. But most of the time users are happy with more breadth or depth only where it’s needed.