Last updated: December 1, 2021
There are various approaches you can take to structure and define your IT documentation. One of these approaches is based on ITIL. ITIL stands for IT Infrastructure Library, a set of guidelines which is currently available in version 3. For your IT documentation, you can make use of one of the components from this library, which refers to the creation and maintenance of a service catalogue and a service portfolio.
Service catalogue for technical documentation
Let us start with the catalogue. Simply put, a service catalogue subdivides your IT landscape into individual, functionally independent units (comparable to the drawers of a cabinet). The cabinet which holds these drawers is your computing system. This means that you are creating functionally related arrangements or groups, enabling you to associate the IT systems, software, services, and processes you have in use – the so-called assets – with specific services. It must be possible to associate each asset with a service. An asset which does not lend itself to being associated this way is perhaps no longer needed or might require a separate service. The arrangement also includes passwords, licenses, and service agreements. Examples of such functional arrangements or groups might be E-Mail, Internet Access, Firewall, Server Operation, or Workplace Equipment.
It is up to you to define which asset belongs to which drawer. When saving your documents, this will also enable you to associate the corresponding files with a service. Thus, you obtain an overview of all services of the IT department, classified by subject, i.e. your entire computing system is subdivided into smaller units. By the way, these units are called System Groups in the Docusnap documentation tool.
A service catalogue describes the so-called infrastructure services, i.e. it is intended as a technical description. Since only a limited group of people may access the service catalogue, you can also document sensible information such as passwords and license keys there. Associate all pieces of information with the corresponding services, including passwords and license keys. But make sure that this data is only contained in the technical description, i.e. in the service catalogue! With all this information, including sensible data, the service catalogue must be treated as an internal IT document and access to it must be restricted. For this purpose, apply the need-to-know principle for permissions assignment.
Another very interesting side effect, as I see it, is that all IT systems which finally cannot be associated with a drawer are probably no longer needed and can be discarded. After all, why are devices in use if they cannot be associated with any service? This means that you clear up your network along the way, thereby reducing energy costs and the generation of heat in the respective rooms. These are quite nice side effects, aren’t they?
A service portfolio describes the IT services for the users
And now a word on the portfolio. What, for heaven’s sake, is that? A service portfolio describes the so-called business services. It serves as a reference for your customers so that they can understand the purpose of a particular service. One of the services, for example, is called “E-Mail” and should be found in every company today. You can then associate one or more infrastructure services with this “E-Mail” business service, e.g. “E-Mail Server”, “Spam Filter”, “Virus Scanner”, or “E-Mail Archive”. These represent everything that is executed in the background to enable this service. In fact, your customers will not be interested in these details which are only interesting for members of the IT department, and they are the only ones who are supposed to understand the service catalogue. But the customers need to understand the service portfolio, and this is why it must not be presented as a technical description. It will (probably) not matter to the user if you operate your own mail servers or rely on a webmail provider. The only thing the user wants to do is to write e-mails.
Service number as a unique feature
Identify each service by a unique number. Here, you must make a distinction between the service catalogue and the service portfolio. For example, you may use IT-SF-xx for the service catalogue. IT-SF stands for IT–Service Folder, xx is a consecutive number. Write this service number on every invoice that relates to an IT purchase. The service number is similar to a file reference. Refine this approach and create an additional subdivision by hardware, software, services, maintenance, and consumables by simply adding corresponding identifiers to the invoices. Document the costs and the associations in a separate table or ask Accounting or Controlling to provide evaluation methods. In the end, you finally obtain a practical evaluation showing which services your budget was expended for. This way, you can analyse costs more easily and estimate them more accurately in the future.
The search for information will also be easier then. For example, if you need the license number for a software product, but do not know under which system group it was saved, you still know what the software is used for. Simply display all license numbers for the corresponding system group. The number of hits will be smaller, simplifying your search. The subdivision into system groups reduces the number of potential hits and you can use entirely new search criteria.
It is recommended to use a different numbering scheme for the service portfolio. This also provides a visual distinction and you will get along more easily. You might choose to use BS-xx, where BS represents Business Service and xx stands for a consecutive number again. Finally, append a short, descriptive name to the number. This makes things easier for your users and customers.
Summary
The services in the service catalogue are called infrastructure services and described there with a focus on the technological aspects. The infrastructure services are finally aggregated into business services. These business services are described in the service portfolio and are intended for the customers of the IT department only. Each business service describes the business context in which the service can be used, the so-called business case. This, in turn, describes the added value the service provides for the customer. The service portfolio must not be written as a technical description, but rather from a marketing or sales perspective.
In the Docusnap documentation tool, you can map such service groups in many modules, including the service numbers This applies to the IT relations, IT concepts, the documentation of passwords or adding software licenses and contracts. This arrangement scheme may be used almost everywhere.