Architecture decision record and inventory forms

Pick the record you need to capture — a decision, a requirement, a constraint, an application, a flow — keep the questions that fit your organisation, and you get a link to a form that asks them. Send it to the person who holds the answer. Nothing is stored here: the form lives in its address. Free, no account.

What it does, and why it is here

Architecture work produces a small number of recurring documents, and almost every team rebuilds their templates from scratch. A decision record, a quality requirement, an entry in an application inventory: each has a shape the discipline settled long ago, and each is usually improvised into a wiki page whose fields differ from the last one somebody wrote.

The cost of improvising shows up later, not sooner. A decision record that omits what else was considered and what it costs us is unreadable in two years — it says what was chosen and nothing about whether the reasoning still holds, which is the only question anyone opens it to answer. A requirement written without a measure is an opinion.

So this page carries the questions, per record type, and turns them into a form you can hand to someone. That last part matters more than the template: the person who knows the answer is rarely the person maintaining the register, and a link is easier to send than a wiki convention to teach.

What you fill in

• Which record — the catalogue covers the decision record, the quality requirement, the constraint, the stakeholder, the business value, and the cartography entries: applications, processes and flows. Choosing one loads the questions that record asks.
• The questions themselves — keep, drop, or add the fields your organisation tracks. The template is a starting point, not a standard to obey.
• Where the answers go — the service that receives them, and the address it gave you. Left as it is, nothing is sent: the answers stay in the browser of whoever fills it in.

What you get back

• A link to the form — copy it, open it, or turn it into a QR code. One link per record type, reusable for every entry.
• The form itself, asking one record’s worth of questions.
• How many questions and how many required, with an estimate of the time to fill in — the number to look at before sending it to fifteen application owners who will each answer it once.
• Which questions carry risk, flagged from the field referential — relevant here mostly for stakeholder records, where names and contact details creep in.

What it does not do

It is not a repository. There is no register, no version history, no diagram and no dependency graph — nothing is stored here at all. This produces the form; where the answers live afterwards is your decision, and it should be somewhere your team already looks.

It does not model anything either. If you want an architecture description you can query, this is upstream of that: it standardises how a record is captured, not how a model is built.

The tool is in beta. A form address already built keeps rendering the same form; what may still change is what the tool can do.

What makes each record worth re-reading

A note on depth, since it is the question every team argues about: record a decision when it is costly to reverse. Choosing a database, a protocol or a boundary is worth a record; choosing a variable name is not. And decisions are captured one at a time, in the moment — a record written six months later is a reconstruction, and it reads like one.

Questions

Is it really free? Do I need an account?

Free, and there is no account — nothing is stored here for one to hold.

Where is the form itself stored?

In its link. The address encodes the form, so it keeps working without anything here staying alive.

Is this a repository?

No. It builds the form; the answers go to a destination you choose and live wherever you put them.

Can I add fields my organisation tracks?

Yes — add them, and drop the ones you do not use. The catalogue is a starting point.

Can I change a record after sharing the link?

Not in place. Rebuild it and you get a new link; the old one goes on rendering exactly the form it always did.

Which standard is this based on?

The common practice rather than one framework: decision records in the form Michael Nygard popularised, quality requirements written as measurable scenarios, and inventory entries of the kind any application cartography keeps.

How long should a decision record be?

A page. Context, the decision, the alternatives considered, and the consequences you accept. Anything longer stops being read, which defeats the purpose.

Can an agent use it?

Yes — the tool answers JSON as readily as HTML, so the record catalogue and the form address can both be obtained programmatically.

Sources and further reading

• Architecture decision records — the format, its variants and its tooling.
• Documenting architecture decisions — Michael Nygard’s original piece.
• ISO/IEC/IEEE 42010 — architecture description, and what a stakeholder concern is.