Project Description
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.
Solution Manager has a prescriptive approach of how to document the solution. Libraries are filled with objects executed or development, and documents must be assigned to the processes and process steps that use them. These rules create a standard layout so that anyone looking for documentation knows how to navigate the tool and where to find what they need. Describing the system is no longer something that must be pieced together from long hours of knowledge gathering. As anyone can successfully get the information they require, the necessity for retaining key resources who “understand the system” is avoided.
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.
A document describing the implemented solution is snapshot from a certain point in time. Many changes to the documents and solution occur throughout the lifecycle of a project and having document version control linked with solution change control keeps support information always up to date. While version control is a feature of all documentation solutions, the ability to link change documents to the maintenance and development paths and keep them synchronised with production changes is a level of governance that is costly to maintain outside SAP Solution Manager.
Having an online system with a single database means that multiple copies of the same document can’t exist at different locations. Of course, checking out and back in again is a well-practised mechanism to maintain data integrity. However, there may well be requirements for areas of information to be represented in different documents. The process diagram requires the BPML, the job schedule requires the BPML, and changes to batch programs require the jobs to aligned to development documents. Each area may very well be duplicated and maintained separately, instead of “normalised” in a relational databased sense and therefore impossible to create inconsistencies.
Meta is a prefix derived from the Greek meaning “about itself.” With Solution Manager Process Management, the representation of the documentation is tightly bound up with the solution being documented. For example, interfaces are not only described in their own libraries, but can be traced back to the business process that use them, and the system between which they communicate with, giving context to their purpose. The abstraction from what is built in the managed systems to the process management configuration in Solution Manager is meta information.
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.
Leave A Comment