News for hackers. Stuff that matters.
Re:Writing a good design document by gerdesj on Sunday August 03, 2025 @07:53PM (#44780861)
I'm going to have to read that MF.com link fully and properly but I can't help but notice this:

"That’s it. That’s the Advice Process in its entirety." (speak to everyone involved).

Presumably anyone with the term Managing as a prefix in their job title is expected to glaze over at roughly this point.

Then we get to the meat: "The four supporting Elements". So I try to find out about ADRs:

I follow the first link:

https://www.thoughtworks.com/radar/techniques/lightweight-ar...

and eventually end up with this beauty (big download button at the bottom of the page from above):

https://www.thoughtworks.com/content/dam/thoughtworks/docume...

Would you mind pointing us at an actual definition of ADRs, please?

Re:Writing a good design document by farkin88 on Sunday August 03, 2025 @08:16PM (#44780993)
There are so many external links, it's easy to get lost in this article. Look under content for the section titled "1. A Thinking and Recording Tool: Decision Records." It's under "The Four Supporting Elements." Here's a direct link if it's easier https://martinfowler.com/articles/scaling-architecture-conve... (Just search on that page for "The Four Supporting Elements)

There Harmel-Law defines ADRs as "lightweight documents, frequently stored in source code repositories alongside the artefacts they describe." He also provides a handy "Elements of an ADR" table. Let me know if you're still having problems finding it.

Re:Writing a good design document by gerdesj on Wednesday August 13, 2025 @08:28PM (#44895487)
Thank you for the links. Sorry for the delay.

I do like to wrap up ... eventually! 8)