0009-support-links-between-adrs-inside-an-adrs.md

Support links between ADRs inside an ADRs

Technical Story: adr#9

Considered Options

• Use tables
• Use heading together with a bullet list directly after status
• Use heading together with a bullet list directly after "Decision Outcome"
• Use heading together with a bullet list at the end
• Don't add links

Decision Outcome

Chosen option: "Use heading together with a bullet list at the end", because comes out best (see below).

Pros and Cons of the Options

Use tables

• Good, because easy to write
• Good, because history is shown (enabled by concept)
• Good, because current adr-tools support (npryce/adr-tools#43) uses tables to describe links.
• Bad, because not supported by the CommonMark spec
• Bad, because unclear whether a link was superseeded by another one
• Bad, because valid links not clear at first sight (there might be outdated links shown)

Use heading together with a bullet list directly after status

Example:

• Good, because easy to write
• Good, because supported by the CommonMark spec
• Bad, because not consistent with the status label (refs adr#2)

Use heading together with a bullet list directly after "Decision Outcome"

• Good, because easy to write
• Good, because supported by the CommonMark spec
• Good, because the options are first introduced and then the links
• Good, because consistent with position of "Decision Outcome"
• Bad, because reader might get distracted: He might expect explanation of the options instead of links to something else
• Bad, because not consistent with scientific papers, where related work and future work are coming after the discussion of the content.

Use heading together with a bullet list at the end

• Good, because easy to write
• Good, because supported by the CommonMark spec
• Good, because the options and pros/cons are kept together with the option list.
• Good, because consistent with pattern format

Don't add links

• Good, because template stays minimal