Understanding the Role of Manuals in Software Development

Contents

1. Role of Manuals in Software development
2. Debunking the XP Myth of Code is Documentation
3. Additional value of Good Documentation
4. Role of Technical Writers in XP project
5. Summary

Role of Manuals in Software development
I was reading an interesting article from Ron Jeffries on issue of manuals. I disagree with his assumptions on several aspects. In this article we will take a look at the role of manuals in software development. But first lets see what he has to say on this topic:

• Everyone who has done software products knows that almost no one reads the manual. We know this from the technical support queries we get. We know it because most of us don’t read the manuals either.
• Web apps don’t come with manuals, and they’re kicking butt. Some of them have a couple of help pages. Many have nothing but the instructions on the page and the flow of the buttons.
• More and more software today is delivered on a CD, and the only manual you get is the size of the CD box. Seems to work fine - science has found that more people read those little books - it’s thought that they’re looking for the lyrics.
• And hey: XP projects build the software with the highest business value first. The stuff at the end doesn’t matter as much as the stuff at the beginning!

Manuals are definitely not needed for a simplistic shopping cart type web application, nor are they needed for many other such simplistic applications. However to say that “almost no one reads the manual” is farthest from truth as it can be. For any moderately complex enterprise class applications (Siebel, Oracle, SalesForce, Extensity Expense Report and gazillion others) which require significant user interaction and expresses complex business logic, reading the manual is obligatory if you do not want to mess up in major way.

Not all applications can be made so simple as to not require a manual. The underlying business logic determines the degree of complexity of the application. His article seems focussed on small simplistic applications only.

Several web applications I have worked with and developed does come with full set of manuals. Try creating a complex bioinformatics applications (not just a simple search like NCBI) without a manual.

The rest of the arguments against a decent manual is political-speech-type without much logic. So I wouldn’t spend time to refute them point by point except the final one.

> And hey: XP projects build the software with the highest business value first. The stuff at the end doesn’t matter as much as the stuff at the beginning!

Well highest business value for most enterprise applications does include making the software understandable to all in clear simple terms and that requires a good clear documentation.

The ground reality is that good manuals are a strong requirement for most enterprise applications.

Debunking the XP Myth of Code is Documentation
“Code is the documentation” (XP mantra) doesn’t cut it in the real world. Customers unfortunately cannot read this fine piece of documentation called code. Heck even developers cannot read some such documentation easily.

Let’s look at this problem from a different angle. Can we make “code is documentation” a reality just for the developers themselves?