If you are planning a major change/upgrade then it is important to define all the relevant deliverables. Documentation is sometimes seen as a lower priority but the right documentation can save valuable money in the longer term.

Support documentation isn’t the same as project documentation.

Project documentation is normally designed to document the work to be done and this can mean that work could be split over several documents e.g. front-end changes, Java/Automation script code changes, interface configurations and BIRT reports. Several people could have delivered the different components.

Support people are normally interested in things like this:

• What is the overall flow?
• How does it work?
• What OOB functionality has been changed?
• What assumptions were used when designing the software e.g. number of messages on the interface
• What are the infrastructure details for new environments e.g. URLs/servers
• How do you trace the flow e.g. messages travelling between systems?
• Are there any new debugging processes?
• What are the possible error situations?
• What problems were seen that weren’t definitely fixed or seen intermittently?
• What were the test cases and did they cover failure situations and how to resolve them?

Standard project documentation will have some of these details buried in amongst other details e.g. new fields, design options.

Support staff will often work with the system as it is delivered and may not be given documentation until a problem occurs.

Support teams will often extract key parts of the project documentation and store it either in their own pictures or memory. A few minutes spent producing support focused documentation can save a lot of time in the longer term.

Two examples illustrate this point.

Interface architecture

Where a process stretches over two systems then there can be a number of elements that have been customised e.g. Java class in Maximo, interface object structure, processing classes, interface tables and components on the far end.

A simple picture that illustrates the components allows support staff to quickly remember the flow. The picture can be enhanced by including references about what to check e.g. size of queue X

Log files to check

Maximo Anywhere installations include several different components, each of which can produce log files that are stored in different locations. A support document could contain a table that indicates the flow and provides the locations of the logs. This type of information will save a lot of time when debugging problems.

What does Support need quickly?

• Write flowcharts that show the flow of data over all the components particularly if the data flows over multiple systems
• Highlight areas that have had complex changes or where the functionality significantly differs from the out of the box functionality
• Design code/scripts with support friendly features e.g. comments/sensible variable names
• Ensure the code repositories have the latest versions of the files. Support staff are likely to decompile the custom code but well commented code can be very useful

When could these documents be prepared?

• Overview flowchart documents could be written during design – they can help identify potential weak points e.g. how would someone monitor the flow of messages?
• Infrastructure details can be prepared as the project is running – the project team are likely to need them to access resources
• Details of the testing need to be made available as soon as the testing completes
• Engage support teams where possible. As a support person I have sat with project members and produced flow charts that have then been used as support documentation