Keeping Documentation Simple.

Why simple documentation?

There are a number of reasons for simple documentation, everything still has to be documented but keeping it simple has a number of advantages. A number of years ago I was privy to a conversation regarding some application documentation, the documentation whilst comprehensive was difficult to use and did not read well and was summed up during a meeting as “Having been translated from Japanese to English by someone who’s first language was Swahili”.

The ability to extract the required reporting and management information was impaired, primarily due the the complexity of the documentation, but also due to a certain fear factor surrounding the application and its use.

There was a revamp of the documentation to make it more useable, but the update took time and there were fairly hefty costs involved. Had there been better management of the documentation and had it been created in parallel with the application, it is likely that the effort and cost of a re-write could have been avoided.

Creating a simple documentation suit from the outset is important, the documentation above assumed that there was a degree of familiarity with the application, this included the documentation used as training materials. The way forward was straight dorward, the production of new training manuals and user manuals – with much simplified content, made a significant difference in a number of areas.

• The users found the training much easier.
• The application support team had documentation that was useable.
• Incident resolution times reduced – although experience and exposure contributed here.
• There was an increase in management confidence in the application.

Much of the pain could have been avoided with some forethought around the documentation, the revised documentation was certainly a part of the application success.

The application above survived a number of corporate mergers and in each case the new customer base was migrated into the application, the users of the application frequently cited the documentation as being very friendly.

So what’s the moral to the above, well unless the document has to have the technical content write in plain language. Do not clutter the document with technical information, refer to other documentation where there is a requirement. But remember that the other documentation becomes a part of your business continuity plan, so it has to be kept with the plan and be accessible to the people who may need to use it.

The person actioning the business continuity plan does not need to know how to set up a CNC machine, the operator does – likewise integrating a server with LDAP – the IT staff need to know how to do it and the person effecting the BCP needs to know it is happening.