If you have ever written documents for your projects you might wonder if there was a better way to write about a topic like how to document the user interface, architecture, or functional specifications. It turns out there are some good resources that you can use to improve both the content and readability of your documents.
The first problem in writing a document is the basic structure and grammar around the document. It turns out there is a book about writing style for technical documents, Microsoft Manual of Style for Technical Publications Third Edition. This book acts as both a guide on what and how to write technical documents. It should be used in conjunction with the all time classic on writing style, The Chicago Manual of Style.
In this book you will find described document types and how-tos. Also how to use a word or plural of a word for example "data". What is the plural of data? It even includes topics for programmers on how to write comments and document logic.
The other absolute important resource is Joel on Software. Joel's book contains priceless information on how to write a good specification that will be read by people. It is not enough to write a good specification, you need to write one that will be read. If no one reads it then the document is not useful.
Combine good writing style with good content can't cure cancer or the software industry's dismal success rate for projects. But it might just allow you to communicate a little bit better.
Comments