We differentiate between documentation and documents. Documentation means the utilisation of information for further use. In our understanding, the aim of documentation is to provide information in written or in any other permanent form (documents) for use according to defined objectives. Documents can therefore be electronic documents like Office files, but can also be printed material, databases (CMDB), archives, images, videos, sound recordings and similar.
No doubt, documentation is important. Let’s look at the why in some detail. One answer is obvious: Documentation is a cornerstone of CSI (Continual Service Improvement). For which other business objectives would high-quality documentation be essential in the area of IT? What other areas come to mind immediately, in which documentation plays a crucial role? We will look at these questions in more detail later on.
Just like in so many areas, the following principle applies for documentation: Quality over quantity. Huge volumes of documents make organisation and maintenance a real challenge, bears the hazard of redundancy and usability will suffer or may even be lost entirely in the end. It is not the number or volume of documentation that counts, but rather the quality of its content. Which are some general and specific criteria to note when judging the quality of documentation? Aside from content issues (completeness/accuracy), which we will look at in more detail in a later chapter, the simple answer is: Usability in accordance with the objectives and stakeholders. All information must be accessible quickly and easily at any time for all authorised individuals. Additionally, the content must be easy to comprehend or be self-explanatory.
We can therefore extrapolate the following functional and non-functional quality criteria:
- Permission & Access Control: A role-based concept in terms of rights and access;
- Change Management: Regular intervals must be set for the verification, assessment and approval of content. A standardised versioning (at least two levels, better three) and approval system must be implemented;
- Usability: Documentation must be structured in a way that is clear and self-explanatory for optimised usability. Simple search functions or links (CMDB, external links, etc.), blogging, chats, video & sound further improve usability;
- Maintainability: Compliance with set norms/standards/conventions;
- Completeness: Completeness in accordance with the defined scope;
These criteria should be known ahead of time and are decisive factors for later assessments. Also the procedure for generating documentation should be known beforehand. Compliance with every step in the procedure can be the difference between success and failure.
Which are the key factors for success to ensure the various objectives and requirements for documentation long-term? Concepts and procedure models are of crucial importance.
The avato procedure model defines documentation as a process with structured levels and clearly defined goals and stakeholders. Specifically, the documentation process evolves the following levels:
- Stakeholder: Identification and specification of stakeholders
- Goals: Definition and prioritisation of objectives
- Scope & Structure: Definition of the areas of documentation (scope) and subdivision into areas of documentation
- Details Goals & Structure: Identification of objectives for each area
- Definition the methodology: templates, teams, roles, approach
- Definition of tools
All levels are worked through at the start of the documentation process. But documentation doesn’t end there. Continuous development and maintenance, guaranteed by periodic reruns of the process is an integral part of the documentation procedure. Part of the documentation procedure is also the definition of steps and intervals to be repeated.
Multiple stakeholders generally have very different requirements for documentation in terms of objectives, emphasis and structure. Auditors will presumably focus on the exact description of responsibilities. From an operational and automation objective, the exact “how” will be more important. That is why it is important to know the relevant stakeholders and their objectives and priorities exactly. Typical stakeholders are IT operations, revision (external auditors) or IT governance.
Once the stakeholders and their objectives and priorities are known, these can be aligned and coordinated. The result is then agreed with all stakeholders and ideally put down in writing. Typical objectives for documentation:
- Continual Service Improvement: CSI in terms of standardisation and optimisation
- IT Operations: Instruction and support in day-to-day IT operations; acceleration and quality improvement of recurring tasks; reduction of dependencies involving individuals;
- IT Automation: Detailed process and task descriptions as basis for automation
- Service Agreements: Service contracts with external & internal service levels
- IT Governance: Structured and efficient IT governance (incl. reporting)
- Compliance & Risk Management: incl. internal audits and revisions
- Standardisation & Certifications: Required prerequisites for standardisation and certifications
The result will always be an individualised scope of documentation depending on objective. As a rule, all documentation should be based on a superordinate, cross-organisational model for the various areas of documentation, even if documentation generally only deals with a subset of operations. This will ensure that later expansions of or adjustments to existing areas will not require an alignment of the basic procedure. In the following, we will introduce a superordinate model.
A clear structure and a level model can be defined, once the objectives and priorities for documentation are known. Documentation should furthermore allow maintenance and usability without too much resource requirement. Additionally, an efficiently manageable change process (approval process, version control) must be put in place and an effective and manageable permission and access control system must be ensured.
Experience shows that a structural subdivision into various areas, which can be edited autonomously as long as the overall infrastructure is well balanced, is the best solution.
Which levels/areas (documentation areas) are relevant from the viewpoint of IT and should be managed autonomously?
- Business Processes
- Framework conditions for IT organisation
- IT Security & Data Protection
- IT Services (Service Catalogue)
- IT Organisation & Roles
- IT Projects
- IT Processes (ITIL)
- IT Service Operations: Work Instructions and Runbooks
- IT Continuity Management & DR
- Technical Documentation
The subsequently defined documentation infrastructure addresses the defined stakeholder objectives, serves as an orientation guide and common thread and helps to avoid redundancies.
avato Maturity Model
Documentation is a procedure with the objective of ensuring a state of complete maturity in compliance with defined goals. A model with assessment criteria is essential for achieving maturity. As an example, we will introduce the avato maturity model for IT documentation in the following. The model differentiates between 5 levels for the assessment of the documentation process:
- Initial: Every organisation, every business has documentation. Much of that documentation is generated by chance and without structure. Documents are created using individual approaches, without a common theme and partly in random or chaotic form with standalone objectives. At that level of documentation, scope and quality are unknown.
- Evaluated: Once documentation is “Evaluated”, then all elements of documentation have been viewed and acknowledged and their quality has been assessed (see also: “quality criteria”). Additionally, the documentation objectives and stakeholders have been determined.
- Defined: Documentation is deemed “Defined”, once its objectives, stakeholders and metrics have been specified and a process model and the structure of the documentation into documents/documentation areas have been agreed.
- Managed: Documentation is considered “Managed”, once the documentation content is continuously developed further in line with the defined objectives, metrics and stakeholders.
- Optimising: Documentation is at the “Optimizing” level, when it contributes to achieving the defined objectives. At this level, multiple achievement levels can be defined for each objective. In our experience, typical areas for documentation are:
- Continual Service Improvement
- IT Operations
- IT Automation
- Service Agreements
- IT Governance
- Compliance & Risk Management
- Standardisation & Certifications
In addition to the assessment of the documentation process (five levels), the individual pieces of documentation are assessed as well (maturity index). The actual assessment using the maturity index does not occur until the level “Optimising” is reached.
Example of an assessment of the documentation elements (maturity index) with different documentation objectives:
Maturity Index as diagram:
At the “Optimising” level, documentation is continuously developed further and assessed. In this example, the maturity index varies and deficit areas need addressing and supplementing.
Documentation is always a process. Objectives, emphasis or stakeholders can change over time. An adjustment of objectives means that parts of the analysis must be repeated to ascertain the level of maturity, i.e. to what extent the documentation fulfils the new objectives.
Tools are not a decisive factor for the success of documentation, although using the right tools can be a great help and can assist in designing an overall better and more efficient overall process and utilisation model.
In our experience, the use of Wiki technology, e.g. Media Wiki or Sharepoint Wiki in conjunction with a communication platform for the various individual projects, has proven to be helpful. It is important to specify responsibilities and rules for use ahead of time to ensure optimised maintainability, change processes, security and usability.
As described earlier, documentation is an integral component of IT operational excellence. It offers an overview and clarity, is the basis for basic decisions and opens up new optimisation potential.
Our explanations above have shown that documentation can differ from case to case. Notwithstanding your choice of tools, the value of documentation is directly related to the quality of content and an optimised concept and procedural model.
Content quality ensures the reliable and complete availability of information at any time – for authorised individuals – and allows an efficient change management. High quality furthermore guarantees usability by way of a clearly defined structure and search function.
The avato Maturity Model transports your documentation process to full maturity at the “Optimising” level. The further development of documentation in line with the defined goals of stakeholders and at the desired quality level can only be guaranteed once it has reached the “Optimising” level.
Risk and compliance management, reporting capabilities or continual service improvement in terms of standardisation and optimisation – none of these goals can be achieved without documentation with a high level of maturity.
Operational excellence is multi-faceted and covers many topics, which means there are also multiple approaches.
Date: August 2016
Author: Gregor Bister, Jennifer Gitt
© 2016 avato consulting
© 2019 avato consulting