A Document on Documentation

Recently, I’ve had the opportunity to think about product documentation quite a bit. When it comes to custom software and software-as-a-service in particular, documentation can be a peculiar issue. It is something that is almost universally desired, but at the same time often deliberately minimized or overlooked. I’ve considered this issue and provide some recommendations on best practices for documenting customized software.

Custom software, whether or not it is true in reality, is often perceived as more expensive than out-of-the-box solutions. This can be due to a number of human factors, including the psychological effects of: negotiating a price, time & materials contracts, or non-advertised pricing. The effect on documentation is that often the customer is unwilling to spend the time and capital on extensive documentation. Unfortunately, in many cases, this can have the exact opposite effect. Improper or incomplete documentation can lead to cost overruns, missed deadlines, and scope creep.

Alex Papadimoulis however, in his blog makes a very good case against over-documentation. To summarize Alex, the more complicated that documentation gets the less likely that it is to be accurate and therefore the less likely to be used.

Certainly there is a place for some middle ground and I’m suggesting a few simple rules when it comes to documentation for custom development:

1. Pre-development documentation should be very extensive and detailed.

This protects both the client, who can be sure about the specific deliverables and time-line, as well as the developer who can be protected against scope creep. In addition, extensive pre-development documentation can help locate and resolve potential issues that might otherwise crop up during development damaging the project time-line.

2. Change orders should be specific and limited

It is often beneficial, from a budgetary perspective, to group multiple types of changes into a single purchase order. It is natural to consider similarly grouping the changes into a single change order. Fight this instinct. Of course it is important to have a overall review of changes so that any areas of conversion or diversion can be identified, but each change should have its own: time-line, specific deliverables, and responsibilities. Keep a history of these change orders indexed very thoroughly. It will be most useful when researching functionality in the future.

3. End user documentation should be step-by-step and include examples

End users often don’t care about the specifics of the business rules. Getting daily tasks done is usually more critical. it is important to provide clear, step-by-step instructions for these users.

4. Developer notes should be added to self-documenting code whenever possible

Clarity in source code documentation is often a difficult battle to win, but the principles of self-documenting code: naming conventions, consistency, and uniformity of format are a good starting place. Adding in developer comments for confusing or unusual elements is critical though for good portability of code.

5. Keep system documentation up-to-date

This includes system diagrams, redundancy and backup procedures, and responsibility / contact charts. ‘Nuff said.

Together, these five suggestions should help put your development on the smooth, well documented, path to success.

Follow me on twitter or Add me to a Google+ Circle

Leave a comment

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

%d bloggers like this: