Review By: Peter Gabris
04/16/2012

Like it or not, writing—not writing code, but writing documentation in plain English—is inevitable if you want to make living by developing software. So, you'd better be good at it! This is the case Alan Stavely is making in Writing in Software Development.

I hear you: If only the English language had just a few hundred keywords and BNF rules that could be built into a compiler. Just imagine inserting assert, trace, or debug statements into your essay to see where a reading of the text might go wrong! Yes, this would be the right English language for programmers. Regrettably, people prefer English as it is.

The author first looks at the program code itself, the code readability, and the code comments. He does not argue for self-documenting code as the only documentation, and I am grateful for that. I remember seeing a few real cases with beautiful code that told the complete story. Mainly, complex algorithms can and should be coded that way. However, the breed of code that most of us have to write—a code for corporate use—is simple in detail but complex in the volume of those details. Therefore, it requires documentation at a higher level. The book looks closely at options to merge the code and the documentation into a single document, a technique called "literate programming."

There are many more categories of writing in software development, and the book pays appropriate attention to each of them, including design documents, proposals, requirement and specification documents, communication between development team members, user manuals, and tutorials. The primary attention is on what to put in than how to put it, and this is good.

Writing in Software Development earned already a distinguished place on my reference bookshelf, and it should be on yours, too. You will use it for a long time, because reading a sloppy documentation on an iPad is not any better than reading it on printouts. Even if you do not have time to study the whole book right away, turn to page 57 and read “Documentation by the Pound.” And, do not forget to show it to your colleagues, developers, software suppliers, and perhaps to your boss, too.