Thoughts and Opinions on Technical Writing
Can a technical writer produce good software documentation without understanding the software? Probably not.
Good technical writing is founded upon plain good writing. Focusing on a document's purpose, the writer organizes information using logical principles such as grouping and sequence. In many ways, technical writing is primarily a process of organizing and structuring existing information.
Documents that are well organized are easy to read and easy to improve. The better a technical document's organization, the easier it is to evaluate the quality of its writing and suggest improvements. This relationship between a technical document's organization and the ease with which its writing can be evaluated is so strong that the possibility of a helpful critique depends almost entirely on the document's organization. However, the relationship does not hold infinitely. Attempts to improve a document beyond some point typically require modifying its organization, its logical structure, thus risking its present quality.
Well-written technical documents are produced through re-thinking, re-organizing, re-writing, and further editing. This iterative process is what we do to produce not just documentation; it's also what we do to produce software. From a single sentence to a documentation set, and from a single line of code to a family of software products, we iteratively organize information. Complex ideas can often be made clearer with simple techniques, such as breaking a long sentence into two sentences, using active voice when appropriate, abstracting essential ideas, summarizing etc. Software is refined in similar ways with recursion, iteration, abstraction through object oriented programming, shared libraries, etc. Whether writing software or technical documentation, we essentially use the same techniques. When the organizing and structuring is complete, the document is nearly complete and the program is nearly written. It is almost as if they have written themselves.
A document's structure should reflect the logical organization of its ideas, and a document's formatting should visually express the same. All technical writers can be assigned a DTD or formatting template that dictates a document's data structure or visual format. However, even technical writers who can generally write very well, but can't organize highly complex ideas in the information before them, usually produce poorly-written documents. As technical writers, when we lack the necessary fundamental knowledge of a subject, we are simply unable to organize the information because we:
The solution is for technical writers to be sufficiently knowledgeable of the technology about which they are writing. Ideally, technical writers would possess a general understanding of a subject significantly in excess of what their readers possess. In this way, writers develop the proper context and bring to a document a sense of authority to which readers respond with trust.
The investments in training are immense. In a spirit of fairness to technical writers, who may require expertise in many different areas of science and technology, there is a limit beyond which additional investments in education and training are not economical. Most likely, and I mean this purely on an abstract macro level, the point at which a society cannot afford the necessary investments required to communicate its technology is a point of inflection at which the value of that society's technology ceases its acceleration. And although perhaps still continuing its increase in value, next comes a decline.