Some background: I am indeed interested in writing documentation, for myself and for others.

The initial trigger is usually to note it down for my future self, and/or for helping me to understand a topic better; if it’s also useful for others: great.

And while I don’t spend too much time thinking about software documentation, I occassionally stumble on some interesting things…

Audience of Documentation

There are different schools of thought on how to distinguish the audience for which specific documenation is created.

Mostly they split it according to the level of proficiency/competency, which I’m fine with, but in my opinion, one should also always consider that this level is in a certain state of flow: One can’t know everything and one should also never stop learning!).

Often, five levels are used, but I currently think four should also be fine:

1. Level: Novice/Beginner
2. Level: Advanced/Intermediate student
3. Level: Proficient/Competent apprentice/journeyman
4. Level: Master/Expert

Diátaxis Documentation Framework

Recently (and coincidentally), I stumbled upon this blog post about the Diátaxis Documentation Framework.
I had never heard about it before, but I liked what I read in this blog post.

As I learned a bit more about this, one complain I repeatedly read was that this concept isn’t groundbreaking (“That’s just Technical Writing 101!” or “That’s just what DITA did, 20 years ago!”). Well, that may be so, but:
a. I haven’t studied Technical Writing, nor do I plan to.
b. DITA appears very technical and detailed, while Diátaxis seems to be more of a general framework, collection of guidelines or a philosophy of documentation design

Essentially, it splits technical documentation in one of four types, which are based on the needs of the user (consumer) of it; I like that approach:

… or in a slightly different representation, based on the axles that the sectors provide:

                     |
    Tutorials    (PRACTICE)   Guides
                     |
------ (STUDY) ------+------ (WORK) ------
                     |
   Explanation    (THEORY)   Reference
                     |

Other articles:

• Diátaxis, a new foundation for Canonical documentation
• What is Diátaxis and should you be using it with your documentation?
• Diátaxis framework: The best documentation model?

Architecture Decision Records (ADRs)

A while ago, I learned about the concept of Architecture Decision Records (ADR), which are a good idea for long-term strategy decisions:
The idea behind ADRs is to document or log important decisions related to the design and architecture of a (software) product or service.

It’s based on “Documenting Architecture Decisions” by Michael Nygard, published in 2011, where he introduced the format for an Architecture Decision Record (ADR).

I had heard about this some years ago, and liked the concept, but hadn’t an immediat need for it in my line of work/hobby.

Nevertheless, I still like the premise, and maybe some day, might make real use of it.

But for now, I’ll just try to condense the key points here, as a reference and guidance for my future self and anyone else who may be interested.

In the original posting, ADRs are meant for “architecturally significant decisions”, thus the name.

Which is fine, but in my mind, I often substitute “Architecture” with “Design” (or a similar term), to make it clear that those records are meant for any important decision for a product/service/project. Anyways, that’s just a side-note; I’ll stick with the popular and known name/abbreviation (ADR).

Basics

• Keep an ADR short/brief/compact; not too long (around 1-2 pages) and not too much details (one can link to other documents).
• Keep it simple: No special, proprietary tools or formats needed: Plain text files (for instance as Markdown) are good enough.
• Keep ADRs close to the codebase (e.g. in the same repository) or centralised at the same location (e.g. if they affect multiple codebases/projects); for easy lookup and search.
• Not every small decision needs an ADR: It’s meant for essential decisions that influence the core design of a product/service.
• Use an active voice when writing the text.
• An ADR should be immutable (except for minor modifcations, for example fixing typographical errors); but it can be superseded by a newer ADR.
  This useful for building a history, where you can trace, when and why a decision was made.
• While one should not stray too far away from the common ADR defaults, the format itself is not set in stone:
  Extend and adjust it to fit your needs (e.g. with other status terms, additional sections, etc.).

Structure

Here’s (my) simple template (in Markdown syntax) for an ADR:

# <ID> - <Title>
<Timestamp>, <Author>

## Status

## Context

## Decision

## Consequences

## <Metadata|Notes>

Doxygen

I also “rediscovered” Doxygen for me, which is helpful for the auto-generation of reference material, and also useful as a guidelines when documenting the source code in general.

I have used Doxygen before, but not very extensively; and over the last years (due life circumstances), it fell by the wayside. But now, I’ll it more again, and thus there is a dedicated “cheatsheet”, which has its 👉 own page now.