The day I got inducted into my first stint as a technical writer, I knew what I would do, but I did not know how to convert thoughts into expressions. May be I had hit the writer’s block, and because it was the first day of the job, none of them raised their brows to it – and I shrugged the thoughts off, thinking those as natural. Had I known how to use the standards/rules for documentation, which I later got to know when prepared product-level documentation, may be, just may be, I would not have hit the block. Or, the tasks given to me would have appeared easier.
My first day with technical writing taught me about the need of standards – the need to formalize our product-related communication, the need to proportionately distribute information across paragraphs in an essay, the need to write (or communicate) correctly, clearly, completely, and coherently (See my previous post on the seven signs of highly effective content), and the need to not to make mistakes and miss any information.
In technical writing, it is all about the only two aspects: technicality and writing. And in writing, in turn, it is about the correctness in the use of grammar, punctuation, syntax, word/s, and hence, sentences, paragraphs, and essays.
We know we have previously discussed, writing is more an art than a skill. And hence, it is possible that even when dealing with a subject as technical (and methodical in approach) as technical writing itself, no two of us will write alike. It is therefore important to have standards and rules for documentation in place.
Of course, having rules in place neither stops one from showing creative approach towards documenting procedures, nor does it implement at fool-proof system of documentation. Mistakes, misses, or oversights will still happen. And, as writers, we cannot stop committing them. But, we certainly can control the recurrence. And, that’s the very purpose of laying standard rules and processes for documentation.
Keeping aside the technicality involved in documentation procedures, we see that it is only the rules of grammar that writing is left with. But, for the purpose of this post, I will not use any of those parts of speech or gerunds to tell you what to keep in mind when establishing the standards.
I do not have an exhaustive list of what could be the candidates of standards for documentation, but I can provide you with some organization-level understanding of everyday scenarios.
Follow a Style Guide
Now, it is not a mandate, but style guides, such as the Microsoft Manual of Style for Technical Publications and Chicago Manual of Style provide detail-level standard rules and procedures. A style guide may also mean a document specific to your organization; the idea here is to establish standards for documentation. Not only does it avoid chances of the writer’s block, it enables protection of content as well. We will talk about it in detail as we read ahead.
Have a company-specific rule book
It is good to have some standards in place when you know that the company is expanding its operations and may be soon there will be more, new writers who do not know about products, tools, or even language. The company-specific rule book contains ready-made, reusable content (per se, lines or paragraphs that include product-level or object-level information), and insights for your newer (fresh?) colleagues.
Study the market
It is important that documentation does what you expect it to do – provide instructions and product-based information. Language evolves continually. Therefore, documentation too must evolve to ensure congruence with latest trends and processes. One should strike a balance when creating standards. Having too much of standards (or having water-tight definitions for documentation) for a dynamic industry will only increase rework, physical labor, and cost.
Be proactive
Now, that’s really important; being a trend-follower, in my opinion, is easier. But, to read the market and come up with your own guidelines, and eventually, influence the market is a real challenge. Read the market, and bring innovative approaches to help save time, cost, and labor. A major part of agile methodology deals with delivering quality documentation, while meeting tight deadlines. But, it only increases work pressure if you are dealing with products that involve constant upgrade and evolution. In such cases, meeting deadlines for delivering documents that are error-free is a tough task to accomplish. If you are proactive, you will have rules in place to deal with such problems. For example, if your company allows single source publishing, not only will you save on the managerial dynamics, you will meet tight deadlines as well.
Conduct meetings
Conduct internal meetings every week or month, to validate the need and role of standards in documentation. Having standard processes and test-cases will help deliver content in time, but what if the content does not meet the requirements at all? What if the processes were not updated regularly to meet customer demands? Answer such questions in advance and steer your documentation team into a direction which is both, effective and efficient.
So far, we have discussed a lot about the need for standards, and what we need to do once we have them in process. But, just to consolidate our understanding, I have collected some scenarios each one of us comes across when preparing documentation on a typical day:
Whether or not?
It feels helpless when no one understands why not to use “or not” in a sentence. They only reason I do not explain is that I cannot. One must build his/her own understanding on this. “Or not” is an unnecessary inclusion in sentences that introduce nouns. Imagine a sentence: “This column indicates whether the chart of accounts is enabled or not”. I found only one apt reply (on the internet) in this regard.
For more information
It is probably one of the most debated topics we have. There are numerous occasions when we must refer to readers about Web sites and blogs. In such cases, points like “for MORE information” or “for MORE reference” are a tautology, because having a hyperlink itself makes it understood that the information in the link will be “more” in quantity (and quality, though only occasionally!). So, to say “for MORE information” doesn’t really make any sense. The sad thing is that our “sense” isn’t really that common!
The reason is because
Another classic example of tautology is the mention of reason and the reason for the reason in the same sentence: “The reason why I did this is because”. Wow! Now, as I said, it is common for us to find our reasoning uncommon. Perhaps, this is why we are such highly paid (and respected?) professionals. Think about it: Doesn’t this point qualify as one of the perfect candidates for standardization?
For only once
Do not – I repeat, do not – use only with something, which is not modified in the sentence. A classic example of why I insist is (“because”) placing of the word only in a sentence such as the following will change the meaning with each change of place: “I have seen your new book”. Practice placing “only” in different places and you will notice the change in the meaning. Let me try that for you:
– Only I have seen your new book
– I only have seen your new book
– I have seen only your new book
– I have seen only your new book.
As technical writers, we do a lot of things that others do not/cannot; and do NOT do a lot of things that others do conveniently. The idea of this post was only to provide an insight on importance guidelines can be in documentation.
Standards and rules for documentation are only guidelines and do not, in any manner, govern the documentation. The idea is to keep a check on what goes “out” of a company. Words, as we know, are silent ambassadors. They tell a lot about us, before we begin speaking about ourselves.
The Wordsmith 