Living documentation

A guide to organisational information management using a Living Documentation approach

If you would like to support the on-going development of this, please buy me a coffee

You can view a sample organisations documentation at sample.livingdoco.com

Problem Definition

Every organization has to answer the question how do we document and support our IT systems?

At most companies you find a disorganized, duplicated, dis-joined, incoherent, semi complete, inaccessible, unmaintained wasteland of share-point sites, word documents, tooling, and wiki's.

This usually occurs because of the nature of projects (which is related to the nature of funding models). Documentation is created through the viewpoint of a project, then once the project closes the maintenance of the documentation ceases. It's also the effect of ‘working' documentation i.e processing required to analyze and design a discrete problem being used for on going support documentation.

The other main issue is the incoherence of documentation. For example different users will refer to different truths and granularity of documentation, example architects referring to EA Sparx, Developers referring to code, Business Analysts to word documents.

The answer is to create minimum, coherent, up to date documentation that anyone can access and amend. Most importantly it needs to follow a ‘meta-model' which can describe IT systems, scale, and be at a level of granularity which is useful to architects, developers, testers, operations.

Where this can go wrong, is when a an untested, arbitrary information classification approach is used. If you create a structure that does not classify information in a useful, obvious, discoverable and scalable way, users will follow the path of least resistance. They won't use it because they can't find the information and instead will create their own silo's of ‘notes'. They will put information where ever they can, because the convention used is not intuitive or doesn't allow for some deviation.

One of the approaches I have used for the last 10 years is what I refer to as ‘living documentation'. It works well, scales across an organisation and provides a gradual, concise way to document an organisation and its IT systems.

To document, model and support systems at an organisation the meta-model needs to address the audience (business analysis, developer, operations, architecture), it also needs to be at the right level of granularity (too detailed and it is technical noise, too high level and it is abstract waffle). Below is a convention based approach to documenting the IT systems at a company.

Below is a tutorial of how to categorize and structure your organizations IT information using the Living Documentation approach I have been using since 2010. Each section will have a ‘rationale' link to help explain why the approach works.