asciidoc templates

This is my personal recommendation for AsciiDoc templates to be used in an enterprise environment. This collection was created for my talks about how to document better.

Templates

Templates provided:

• ADR — Any Decission Record

• BLPM — Blameless Post Mortem

ADR

Template: template-adr.adoc

"(Any|Architecture) Decission Record" is a best practice to systematically find good technical solutions and document these decission. This template is heavily inspired by adr/madr. The filenames should be adr-0000-some-short-title.adoc.

The ADR states are defined as following, the emojis helps to show the status quickly.

Table 1. ADR states

Emoji	Status	Description
⚙️	proposed	The ADR is currently WIP or proposed for approval. If the ADR is complex, it is usually written on a feature-branch with an MR.
🚫	rejected	The ADR got rejected and the proposed changes will not be implemented.
✅	accepted	The ADR is accepted, the changes are getting or already being implemented.
☑️	deprecated	The ADR is not relevant anymore.
⏭️	superseded	An ADR with a similar topic has been accepted and "overrides" the decisions taken.
🗑️	discarded	The ADR has been created but never got finished, usually due to changed context.

BLPM

Template: template-blpm.adoc

A "Blameless Post Mortem" is a best practice to review an outage with all stakeholders and find a root cause. This should ensure to not have the problem ever again with the action items defined.

Template is inspired by the Google book "SRE", the template is adapted from github.com/dastergon/postmortem-templates.

Useful links

• Antora

• Vale

• AsciiDoctor Quick Reference

• One sentence per line rule

• Joels ADR

• blamess.com

• github.com/dastergon/postmortem-templates