IT Documentation - The Blog

Best Practice for IT Documentation

June 14, 2013

Those who work in the IT sector will – one day or another – be faced with the topic of IT documentation. A chore that nobody likes to tackle. Many do not know how to address it and what they have to pay attention to. First, it is important to consider some basic questions: What is the documentation needed for? Who is it intended for? Why must it be created at all? These questions are legitimate as IT documentation serves different purposes such as:

– define what is needed for a project (requirements catalog)

– capture the structure of an IT network so that errors can be eliminated quickly (emergency manual)

– explain the operation of an IT network (operating manual)

When the purpose of the IT documentation is clear, the next thing is to consider the target group. It may include:

  • users (i.e. the actual users of the IT network)
  • technical staff (such as software developers)
  • administrative staff (e.g. project leads, HR managers, etc.)

IT documentation often lacks a (clear) structure. So, it is not surprising that reading hundreds of pages turns out to be a drag. This is why IT documentation needs to be subdivided into logical units. Depending on the requirements, these can be quite different, but these five parts can be considered as standard:

  • Cover sheet (logo, title, author, version, date)
  • Table of contents
  • Introduction (summarizing the content)
  • Content (as specified in the documentation requirements)
  • Appendix

The content, i.e. the documents to be comprised, is predetermined in many companies by standards or templates. If this is not the case, a Google search for samples may be helpful. In any case, illustrate your network information by adding pictures and diagrams. Visualizations make it easier to grasp correlations. However, make sure that the graphics and diagrams correspond to the text and are duly explained. To relieve yourself from tedious manual work, better use a suitable software program.

For more on this topic: Professional IT Documentation with Docusnap