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.
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.
A collection of Wiki Sections and Sub Sections to describe your organizations IT applications and processes.
Architecture templates, diagrams and technology roadmaps
An inventory of Applications and API's
Databases, Tables, Queues, and Data lineage
A collection of logical and physical environments
Short lived, temporal documentation related to projects
Long lived information describing business domains.
Operations, Support and Monitoring
An inventory of technology in use and adoption roadmaps
Templates for daily standups, decisions, issues, risks and meetings
For more blog articles regarding living documentation see the blog deliveryfundamentals.com