IT Documentation - The Blog

Best Practice for Documentation Management

June 14, 2013

Regular document updates are necessary. Everybody knows this, but must people fail in this task: The security concept has not been updated for more than a year, there is an outdated version of the IT emergency manual on the shelf and only the authors of the concept papers know where the current versions can be found. Without a fixed set of rules for regular document review and revision, this state of things is unlikely to change. It is not for nothing that most standards request to establish processes for document and record control. To enforce these rules in a company, it is important to create a documentation guideline and adopt it as mandatory.

Documentation management needs rules

If you ask IT staff for a documentation guideline or other mandatory documentation standards, they will usually shrug their shoulders. This is a pity because this way, many IT organizations deny themselves an important tool to enforce guidelines and standards. It is advisable that the documentation guideline includes at least the following items:

  • Rules for content, structure, and layout of the documents (versioning, naming conventions, etc.)
  • Rules for the formal design of individual documents
  • Rules for the documentation processes including responsibilities (assignment processes, review procedures, approval processes, etc.)

IT terms must be unambiguous

Besides the standards for the actual documentation, a documentation guideline has yet another benefit: It defines consistent terminology—a fact which is extremely important, especially for IT documentation. Indeed, there is something like a Babylonian confusion in the IT sector with respect to the naming of documents.

And a documentation guideline can do even more. It can be used as a foundation when setting up a documentation management system, i.e. a system where documents are subject to a controlled life cycle thus effectively supporting the IT services and processes. After all, documents are not an end in themselves, but they should provide benefit to the people using them. And for this purposes, they must be up-to-date.