Documentation and Support

Phil Wainewright and his ZDNet colleagues are producing a set of IT commandments. Phil's latest commandment is "Thou shalt document all thy works".

Documentation is the lifeblood of collaborative computing ... How is anyone supposed to reuse a piece of code or a service if the documentation's inadequate?

... And when I say 'document' ... I'm talking about a veritable cornucopia of practical information: what the program does and how is just the start. Other people need to know what it was and wasn't designed for; how it performs and what the limitations are; how it's been tested and what the results were; along with a host of other things.

Many people regard documentation as a tedious virtue - something you only do because there is a parental voice in the back of your head nagging you to do it. Or you find excuses not to do it, or to do it later, or whatever. Or you fantasize that the next generation of technology will be clever enough to generate perfect documentation retrospectively.

The trouble with documentation is that you may have to anticipate all the questions that potential users might ask, and then express the answers in a form that potential users might understand. Modelling helps, because the models can (under certain conditions) provide a lot of the documentation, in a commonly recognized (and possibly machine-readable) form. But models don't always provide all the information the user might want.

What is this information?

• Has this service been used in this context, and how did it perform?
• Can this service handle transaction volumes within this range?
• Why am I getting this effect? Is is supposed to do that, or is it a bug? Is there a workaround?
  
• Are there any known security issues?
• Are there any known interoperability problems when using this together with service Y?
• How quickly does the service provider deal with problems?
• Does this service really work, and can I rely on it?

Are the developers the best people to provide this information? Not necessarily. Isn't it sometimes better to ask other users? And not just the users selected by the service provider to provide glowing references either.

Which brings me to an idea I proposed a long time ago in the context of software quality management - user-led quality documentation. If you are using a service, you should be able to do two things. Firstly you can publish a view of your use of the service, including how you are using it, in what context, what you are using it for, what service levels you are getting, what issues/problems you are having. (Some of this can be automatically generated from your service management system, including problem tracking. Of course, you can control how much of this you choose to expose to fellow users inside your own organization and/or outside.) Secondly you should be able to subscribe to other people using the same service, filtered in various ways.

Service providers (including developers) will want to be active participants in this user community. Of course, the software industry is familiar with the concept of user group - but this has traditionally been organized for very large software products and platforms. A three-day conference in Florida or Vegas, attended by thousands, and carefully orchestrated either by the vendor, or by an independent organization that depends on the vendor's goodwill.

Does this absolve the developer of the responsibility to document? Not at all. But we should no longer expect the developer to be the sole source of documentation. Phil's commandment is consistent with a push model of documentation - perhaps it's time to combine this with a pull model.

Technorati Tags: documentation publish+subscribe quality SOA service-oriented