If you’ve ever struggled with a poorly written doc, and if you say to yourself – “I could write a better document than that!”. Then, you already have a gene for technical writing.
As a technical writer, the goal is to improve or create product documents until the products become so intuitive and straightforward that users don’t need help using /running them or figuring out what’s wrong when they don’t run.
The quality of documentation is actually in the eye of the beholder. i.e., the perception of writing quality is subjective. However, no matter what user you are writing for, there are specific attributes that all documentation should have before it can be considered reasonable. Depending on the quality attribute that you are working with, you will be toggling between wearing two hats, or you may be wearing both hats.
Let’s briefly discuss 5Cs & 2 Hats.
Five Cs
Consider these 5 Cs — correctness, completeness, clarity, consistency, and conciseness — as five test case scenarios the technical document should pass.
1. Correctness
Take a guess! What counts more than crispy writing, exemplary grammar, friendly accessibility, and lovely design?
Accuracy, of course! Nothing shatters trust faster than the reader discovering that information written is wrong. A slight inaccuracy can confuse and annoy your readers; a significant inaccuracy can be dangerous and expensive.
When I say accuracy, it is not just about being technically accurate; accuracy is a question of ethics too. Technical documents must be as objective and unbiased as you can make them. Don’t forget that accuracy is the twin brother of honesty — You need to tell the facts and not mislead the reader.
Fast is fine, but accuracy is everything — Wyatt Earp
2. Completeness
A good document provides all the details readers need. Incompleteness is another form of inaccuracy when you omit a crucial step from a procedure or don’t include an important topic.
A comprehensive document provides readers with complete, self-contained coverage. It describes the background so readers unfamiliar with the subject can understand it. It contains sufficient detail so readers can follow the discussion and complete the required tasks. It refers to supporting materials clearly or includes them as cross-references.
The challenge is it’s hard to see what’s not there. Up-front planning is the best way to deal with this.
Quality is determined by accuracy and completeness — Larry Sanger
3. Clarity
A clear document adheres to grammar, punctuation, spelling, mechanics, and usage conventions. Often, syntactically incorrect writing can confuse readers; sometimes, it makes the writing inaccurate.
4. Consistency
When I talk about consistency, I want to highlight two areas:
- Terminology: Sameness is not dullness in technical writing. Good documentation always uses the same word or term to mean the same thing — every time. Using different names to mean the same thing can only create confusion.
- Structure: Your document should adhere to the established format or layout. In other words, the structure should be consistent as well.
Creating ubiquitous language and adhering to that will bring strong consistency to your product documentation.
5. Conciseness
Conciseness is a desirable characteristic of technical writing. A document must be concise enough to be helpful to a busy reader. At the same time, it should not compromise correctness and completeness in the name of conciseness.
Studies say that you can shorten most writing by ten to twenty percent simply by eliminating unnecessary phrases, choosing shorter words, and using economic grammatical forms.
Conveying information economically is not easy, though.
I have made this letter too long because I did not have the free time to make it shorter — French Mathematician
Two Hats
As a technical writer for a product document, you toggle between wearing two hats — not a surprise — techie and writer.
While in the “techie” hat, keep your eye on correctness and completeness as the primary targets and work your way forward with other Cs. When in the “writer” hat, you pretend to know nothing other than being an audience of the document and break the curse of knowledge bias; focus on clearness, consistency, and conciseness.
The End
Let’s end with the ultimate test — Does the writing have a rhythm and flow?
“Write for the ear,” is standard advice for broadcasters or scriptwriters where the audience hears aloud the scribed words. But I would say this is good advice for technical writers too. Read your writing aloud and see how well the story flows that indicates cohesion — the 6th C.
Like how the code should be considered incomplete until all tests are written and passed, the document should be regarded as not having desired qualities until it passes all Cs.
We’ve all seen lousy documentation and trying to put the finger on why it is lousy. I hope these Cs will help give a name to it, like how code-smell taxonomy helps name the bad code.
and The Beginning
Clarity of writing usually follows clarity of thought. Therefore, when you begin writing a technical document, the foremost step is ensuring you understand the concepts and how dots connect.
We don’t have to be pedantic, but we should reduce the chances of confounding your reader.
There is no such thing as good writing, only good rewriting.
