Writing in Software Development
If you are a working programmer or a programming student, writing is a skill that you can't neglect. Writing is part of any software project, and good writing skills will make you more effective as a software developer.
Writing can enhance your career prospects, too. Sure you can write code to someone else's spec, but what if you got to write the spec? Or the proposal for the project? Writing skills could even help you land your dream job in the first place.
Like no other book on the market, this book talks about writing in all aspects of software development, including:
- Design documents
- documentation in the code and vice versa
- writing for review
- requirements and specifications
- the vision statement, project proposal and project history
- webs of electronic documents
This book tells you how to craft all these kinds of writing to make them as effective as they can be.
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.