The traditional approach to documentation
“Good Documentation is great. But when it’s not, at least you’re getting some.”
Every Service Manager, since forever.
The above reaction illustrates the rather low bar that has sustained many a system support contract. In many people’s experience, handover documentation from project teams tends to be patchy. This is an expensive oversight, as the implications of poor documentation goes beyond only increased support costs. The risks inherent in poor documentation at the disposal of a support teams results in attacks on two fronts:
- Changes have poorly or incompletely understood implications for testing. This means increased risks when changes are transported into Production;
- An increase in time taken to analyse the issue, diagnose the problem and then correctly anticipate remedial actions.
Of course, documentation can always be improved. In the real world, project implementations are very busy times, and the burden of creating documentation is usually met with combining that deliverable with the working documents generated by project teams in the normal course of their day-to-day activities. These working documents broadly align themselves to the following six categories that meet with Kipling’s “six honest serving men – they taught him all he knew”.
- Planning documents, recording the when;
- Workshop outcomes, documenting the why;
- Requirement specifications, describing the what;
- Technical specifications, explaining the how;
- Meeting minutes (and to some extent process diagrams) introducing the who;
- Test results, directing the where.
While this is not claimed to be a complete list, the general approach is both recognised and widely endorsed by implementation projects. However, if consideration is given to what else SAP Solution Manager does when dealing with documentation, it becomes clear that the traditional artefacts created as solution documentation are not as useable or effective as they might be, and so the question is posed: what has been missed off from this list and why should they be considered important?
Solution Manager Process Management
To answer that question consideration should be given to what SAP Solution Manager does provide. The documentation area of Solution Manager comes under the scenario “Process Management”, a holistic term that encompasses implementation tools from project planning to a process centric documentation portal to display documents aligned to business processes.
The following diagram compares the traditional approach of tools with no underlying integration, with Solution Manager Process Management that is designed from the ground up with integration in mind.
The key concept that Solution Manager takes forward is that while information is stored in documents supporting the build phase, supporting the run phase needs a change in approach. This is best characterised by the term “indexing” – all information that was in project deliverables is built into the structural elements of the solution manager portal. This step takes away the reading of “words and pictures on a page” and exposes the concepts in the document to searches, maintains integrity by cross validating the elements with each other, and creates networks between the elements. Therefore, all the prerequisite steps required to understand a solution from traditional sources is done at point of entry, creating a knowledge “warehouse” that can be immediately queried rather than a document repository that requires time and effort to read, understand, and remember.
For example, a process diagram is not treated as a one-dimensional and isolated picture but is directly integrated with a hierarchically represented Business Process Master List (BPML), as is the organisational structure of each role assigned to each step. Ultimately, each object documented in Solution Manager links to the real object in the backend system environment, providing the ultimate guarantee of what it represents is accurate and up to date.
Having recognised places to store information not only works in the direction of extracting information but aids the placing of information. With such an approach, gaps in documentation are more easily identified and plugged.
Thus, friction from moving from the solution to the documentation – and back again from the documentation to the solution – is minimised so they that become a unified representation. This is an advanced realisation of the self-documenting approach in software engineering that aids maintenance and testing. Navigation to a transaction can be by the traditional menu or work centre approach as if an end-user, but also can be by support personnel tracing a process path that brings together any documentation, operating procedures and design background required.
So why document your solution in SAP Solution Manager?
- Integrates and cross-references all the elements of the solution documentation.
- Documentation is kept up-to-date and easy to locate.
- Does away with emails and locally stored spreadsheets as an audit trail.
- Creates synergy by closely aligning with the solution.
Solution Manager was created out of an acute need. SAP was struggling to support expanding their client base with finite resources and found the typical customer’s documentation approach was failing to provide the quality of information they required. Uniquely, they were able to do something about it, mandating exactly how they would wish a customer’s solution should be represented. SAP customers need to know that documenting their solution the SAP way brings in that wealth of experience SAP Business Data Services leverages in providing efficient support.
If you’d like to find out more about SAP’s Solution Documentation and how it can help your organisation, why not contact us for a demo.