Unsolicited Advice for Documentation Engineers Part 1
1. Remove flowery and marketing text.
Documentation should not have marketing text. Describing the advantages and disadvantages of a product, feature or code should be balanced. Promotional writing has no place in technical documentation. For example, indicating that file transfer or throughput is “fast” doesn’t mean anything. By what standards or by what measurement is it “fast”? Will it be considered “fast” next month or even next year?
There is nothing wrong with boring, factual text describing a piece of technology. Every piece of text block should contribute something useful to the reader, not make the document look attractive (e.g. Overview vs. Introduction). A short statement indicating the use and significance of a technology is more than enough - you don't need to append several statements just because another person comments it's too short.
2. Avoid guessing and interpretation.
Although technical writers are not expected to achieve subject matter mastery, writers should not "guess". Using buzzwords repeatedly like "business logic", "implementation", "architecture" and "management" should be used in the right context. There is a tendency for all technical writers to give an interpretation or simplification of input, particularly if the subject-matter is too complicated. Never "interpret" technical information like prose or poetry. If the developer or SME writes a concept a certain way and it is vague or incomplete, do not attempt to guess or Google the concept. Ask the source directly. Your opinion has no place in technical documentation - that's not your job.
When handling extremely complicated technical concepts, break down the technology to understand how it works rather than make holistic, sweeping generalizations just to finish documentation.
3. Identify, describe or define, explain and exemplify.
Identify the concept. Describe or define the concept. Explain only up to a specific degree of complexity. Provide an example to clarify the concept, product or service. Be specific and avoid over explaining.
Over explaining is one of the worst habits of a new technical writer. It shows immaturity and insecurity. Write well instead.
Long text trees and concept hierarchies make it difficult for readers and annoy users with a technical aptitude. Do not make it difficult for the end user by creating endless levels of bullet points, headings, lists and text. Well-written documentation does not require exhaustive, repetitive and redundant multi-level topics.
4. Write for your audience NOT for yourself.
If the end user of the documentation is more technical than you are, then accept it. Just because you don't understand what FQDN or MPLS is, it doesn't mean the network administrator or system integrator reading the documentation won't know what it is. Pretending you understand the technology and then attempt to explain it in the text just produces errors and problems. A technical end user will immediately spot incorrect content no matter how nice you write it. Worst, the technical end user will ignore the text if it was poorly written and “interpreted”. Vague and general explanations are noticed immediately by an educated user.
There is a proper place for explaining basic concepts. If the document is meant for administrators, that document is not the right place for basic definitions and explanations. Again, documentation is NOT about the technical writer. It's about the end user. Never write based on YOUR preference. Respect your reader.
4. Accuracy is more important than language, structure or style.
The value of documentation is in its factuality, not its style or grammar or its adherence to templates. Today’s end users do not care about the structure in a PDF or HTML because digital documentation is designed to be scalable, modular, concept-based and (most importantly) searchable.
What is important is that the text is correct, accurate and useful. Accuracy of technical information is more important than the editor's opinion, the "prescribed structure" of the document, or the sequence of topics. Digital text is flexible and fluid unlike the old static style of user manuals and encyclopedias.
Technical writing is not about English and grammar rules. It's about presenting information accurately, clearly and completely. A misspelled word is less important than an incorrect syntax of a command. In CLI, for example, a full stop can be misinterpreted as part of the syntax of a command.
The more words you write in a technical document, the less clear and less accurate the text becomes. Every word should count and every word should be accurate.
A writer who is more concerned about capitalization, full stops, a missing Oxford comma and sentence fragments is generally overcompensating for their lack of technical understanding of the input. Your editor or co-writer should NOT tell you how to write a document especially if they know less about the topic than you do.
5. Technical documentation is never done or "finished".
Technology and standards are always changing. Just because a piece of documentation was published previously, it doesn't mean it's complete, correct and relevant. In fact, legacy documents are almost often riddled with poor structure, language issues and incomplete and outdated information.
Technical writing means that you follow the life of a document and modify the text as needed, not imitate what has been published before or reuse for the sake of convenience.