Documentation leads the way

During an implementation it is quite often that the user documentation gets down-prioritised compared to delivering the environment and the associated setup documentation (BR100 or similar).

When done in the right way the documentation decreases the overall risk to the project and improves the quality of the delivered system and increases user ownership.

This process involves the users at a early stage so the documentation is made for the users by the users. The benefits of this is many:

  • Better ownership
  • Better readability
  • More targeted to the individual business or department
  • Proven processes at a earlier stage
  • Incorporation of security and controls at a early stage
  • Consultant is a teacher, coach and reviewer for the super user
  • Super User is a teacher and coach for the normal users
  • Improved knowledge transfer
  • Less dependency on consultants post go-live

So it is also obvious then that overall costs would be reduced – especially long term.

The only drawback is increased need for local resources earlier in the project. However the cost of this is easily offset by the savings in consultancy fees.

The list of documents are long but done right the work is minimal and one document inherits the content from another.

This is what I usually recommend to produce – in terms of user related documentation:

  • image High Level Design (HLD) – This document is made by the consultant and outlines the requirements, scope and solution design at a high level. This document is signed-off by the business to ensure the following documents do not expand beyond the overall project scope. 
  • Super User Guide (SUG) – The super user documents the agreed process as it is being implemented and setup in the development environment. The content of this document reflects early testing and decisions made during setup and process design together with the consultant – including exception handling complete with screen dumps.
  • User Guide (UG) – This is the guide for normal users. More or less a direct copy of the above but without the complex exception handling and exception processes. The content is more elaborated and reflect the latest changes so new joiners easily can start operating the system – obtaining a faster time to use ratio. Chapters are the same as in the SUG to ensure ease of maintenance and consistency.
  • Training  Material – this is copied from the UG for the purpose of class room training and easy browsing. Essentially this is the the UG made into a presentation where the screen dumps and charts is used for the slide pages and the body text is added as slide notes.
  • User Acceptance Test (UAT) Script – Copied from the SUG with and added "expected output" and “comments” columns. Using the SUG in this way ensures the system is tested in accordance to the agreed and jointly developed procedures in a comprehensive manner. If any of the test fails it is then easy to make necessary changes to the system and the related documents as they all tie in with each other.

For the benefit of the users both User Guide and Training Material can be put on the intranet for easy access and version control. A tool like SharePoint can be used for this but a more simple approach like saving the document as a web page is better than nothing.

If the above documentation path is not followed you will find yourself faced with some of these issues:

  • Documents are out of sync
  • Documentation takes a lot of time
  • At the integration test stage without super user documentation
  • Consultants runs the integration test (and not the users)
  • At the UAT stage without user documentation or/and training material
  • Documents has to be re-invented or re-done each time in each phase of the project
  • New documents will have to be created after go-live
  • UAT scripts are sparse or not comprehensive
  • Training material not available in presentation format
  • Consultants are making the user guide or training material
  • Users do not know how to update the documentation (try to ask them how they would)

The list could be longer but trust me you will know when something is wrong…