README.md

Living Documentation

A wiki template for living documentation using markdown

Below is a collection of the last 10+ years of conventions I have developed to document IT systems in a wiki style format.

Version 0.2

Introduction

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 lowest energy cost 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.

It’s recommended reading the following tutorials to get an idea on the structure of these living documentation markdown templates.

- Tutorial 1 Applications

- Tutorial 2 Databases

- Tutorial 3 Risks / Issues / Decisions

- Tutorial 4 Logical Environments

- Tutorial 5 Physical Environments

Sections

A collection of Wiki Sections and Sub Sections to describe your organizations IT applications and processes.

Architecture

Architecture templates, diagrams and technology roadmaps

Applications

An inventory of Applications and API’s

Data

Databases, Tables, Queues, and Data lineage

Environments

A collection of logical and physical environments

Projects

Short lived, temporal documentation related to projects

Domains

Long lived information describing business domains.

Operations and Support

Operations, Support and Monitoring

Technology

An inventory of technology in use and adoption roadmaps

Templates

Templates for daily standups, decisions, issues, risks and meetings

Architecture

For more blog articles regarding living documentation see the blog deliveryfundamentals.com