Danny Wahlquist's Mindsay Blog about docbook

I really enjoy reading Steve Whitlatch's perspective on technical writing. As a technical writer and Java programmer, he brings unique insights into the technical problems facing technical writers and the communication problems facing programmers. He is also a frequent contributor to the docbook mailing list. Here is an example of his insight:

"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 and summarizing essential ideas, etc. Software is refined in similar ways with recursion, iteration, abstraction through object oriented programming techniques, shared libraries, etc. Whether writing software or technical documentation, we use essentially the same techniques to organize and structure information. 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."