Interesting article, I think a key thing to establish up front is if the reason is
forward engineering - ie design then coding
or
reverse engineering - from code back to a deduced design
or
maintenance - where the key tracking artefact is a ticket (from customer report through to the engineers change control ticket)
or
a combination of all of them (the ultimate goal for Living documentation)
As they have different motivations and goals. Capturing design decisions in ADRs is step 1 but how to get them relevant to the code?
Add a text reference to the ADR file or ticket number?
Add a hyperlink as a comment in the source?
Make the ADR a sidecar file?
Convert ADR into Text and include in the code, via a well placed tag?
Interesting article, I think a key thing to establish up front is if the reason is
forward engineering - ie design then coding
or
reverse engineering - from code back to a deduced design
or
maintenance - where the key tracking artefact is a ticket (from customer report through to the engineers change control ticket)
or
a combination of all of them (the ultimate goal for Living documentation)
As they have different motivations and goals. Capturing design decisions in ADRs is step 1 but how to get them relevant to the code?
Add a text reference to the ADR file or ticket number?
Add a hyperlink as a comment in the source?
Make the ADR a sidecar file?
Convert ADR into Text and include in the code, via a well placed tag?
More detailed explanation of Living documentation at medium.com/geekculture/living-docu...