Preface
Many IT professionals shy away from their responsibility for updating/creating IT documentation, leaving outdated documentation in their wake.
However, with the right approach and tools, keeping your IT documentation up to date can be more manageable than you think.
In ITSM Company, our two flagship solutions support you with IT documentation practices. Still, this blog is about how we see IT documentation, gives the inspiration to work with IT documentation, and finally, a guideline for implementation.
Why IT Documentation?
Documentation is not a new invention, but the everlasting digital transformation changes the needs and objectives for IT documentation.
Before, we needed the documentation primarily for internal continuity, ensuring that our colleagues (new or old) could operate a given system – or that the front-end staff could handle incidents.
Today, cybersecurity, cloud services, + regulatory compliance changes the IT documentation scope and objectives.
Let’s look at NIS2 as an example. To be compliant – you need to prove it.
To prove it, you need sufficient documentation.
Start with a plan
Documentation is about content, but the content exists in many formats, from operational records to descriptions in Word files.
When we work with IT documentation in ITSM Company, we start to define three kinds of IT documentation:
- Controlling IT-Documentation
- Specific IT-Documentation
- Record-based IT-Documentation
Your governance (or your specific industry) outlines the depth/scope of each of the above types.
Let's take a look at the categories:
Controlling Documentation
Controlling documentation (often very static) is your IT policies, Standard Operating Procedures, Guidelines, Instructions, or whatever you need to CONTROL your digital portfolio and operation.
The controlling documentation can arise from regulations such as ISO 27001, NIS2, ITIL, etc. – but also from industry regulations like WLA-SCS:2020 (World Lottery Association).
Be aware that controlling documentation could also be inherited from a holding company, owners, or even customers.
Specific Documentation
Specific IT documentation is, as the name indicates, a particular kind of documentation related to something.
Specific documentation could be restoring a system in case of disaster (TRP, Technical Restore Plan).
“Related” is essential in working with IT documentation, which means coupling IT documentation together with hyperlinks or other relationships.
In this example, we have a plan linked to a system.
Records Based Documentation
The difference between Specific Documentation and Record Based Documentation can be flotating.
Let’s take ROLES for a given system. Is this a specific or record-based documentation item?
In my optics, it is a record-driven object that can be linked to the system because it will be easy to query the data for reporting, and with the record-based approach, the maintenance will be much easier.
So, whatever you can push from specific to record-driven, the better it is.
Examples of record-based IT documentation:
- Changes (each change is an essential part of your IT documentation)
- Knowledge articles
- IP addresses
- Configuration (of a CI)
Step 1 – use a system
Organize your infrastructure
Using a component-driven model to gain efficiency within your IT documentation practices would be best.
Using your CMDB or a CMS system to create your Service Portfolio, systems, servers, infrastructure parts, apps, and software is best.
The CMDB must keep/support the specific and record-based IT documentation.
Use SharePoint if you do not have a real CMDB. You need a digital list that allows hyperlinks to succeed.
Lesson learned
If you don’t break it down into components, you will create the same documentation multiple times, resulting in a hopeless maintenance effort for you.
Controlling IT documentation – Example
In this example (click for large image), we see a backup policy as a single component linked to our Microsoft 365 Service.
The point is that this backup policy is pure; there are no instructions or configuration documentation.
The example can also give inspiration to working with IT documentation dashboards in Power BI.
IT Documentation best-practice
Create documentation objects/components
Avoid content colliding
Focus on the content in the documentation is the most crucial part, but you must keep things separate.
Example:
You have a SOP for installing a new Virtual Server. An important SOP (a part of your IT documentation) because a new server is related to your cybersecurity.
Usually, an SOP like this has names attached to it – who can change this SOP, who owns this, who is in charge…
If you add names to it, you have started your content colliding. If one of these persons stops in the company, and the name is attached to several documents, the maintenance burden is significant. You end up with insufficient documentation in case of major incidents or cybersecurity events.
USE links instead, and filter in case of name change.
