So the initial question was what belongs into a record and what not? Unfortunately we never really found out and are having a wild mix now, with quite different records. Some of them describe more the philosophy of the project, some describe macro-architectural decisions and others just evaluate different aspects of technology without a real conclusion.

A clear learning here is to separate micro and marco architecture from each other, to avoid lots of confusion of the intended audience - namely developers.

Originally geared toward Markdown-only, we soon reached a limit what can be done with it and we’ve already made the general decision to use AsciiDoc as a documentation format. So I basically picked up an abandoned pull-request which adds this support and also updated the adr-tools to better reflect our way of working.

Although switching to AsciiDoc eased the handling for us writers, it never got much buy in by the teams. The overall preference there was to have a Confluence page, to be able to add comments and have everything just in one place.

Laying out the context of an ADR is sometimes a bit difficult and requires lots of explanations and reasoning, but it probably should never end in just gossip. So we clearly need some boundaries of scope and size of the ADR.

The default output for AsciiDoc is a single page, so handling of it, when there are 40-50 records included, is quite difficult. Also the tooling gets slower and I had to add indexing via sqlite.

We haven’t found a real solution yet, there is a way to split it up, but I have to look into it as my last task on this.

ADR define a fixed structure, but what our version was lacking is a section with either a fitness function or some other means to test, if this ADR has been followed. So we ended up with several records (about 60) and had no means of verifying them.

In my post about [ADR and jqAssistant]({% post_url 2021-03-15-adr-and-jqassistant %}) I basically laid out how this can be easily done with jqAssistant, but we never had the time to look into that.