I wonder if there are others using ADRs for documenting their decisions.

  • mark
    link
    fedilink
    English
    arrow-up
    5
    ·
    1 year ago

    We use them at my company. I love how new engineers can’t just come into our codebase and start doing huge refactors. ADRs kind of force them to explain their rationale. We also use them to upvote on whether an architectural change should be implemented or not.

    • douglasg14b
      link
      fedilink
      English
      arrow-up
      2
      ·
      1 year ago

      How difficult would you expect it to be to go back and produce ADRs for significant decisions in the past that resulted in the current architecture and structure of a small-medium sized project?

      • mark
        link
        fedilink
        English
        arrow-up
        1
        ·
        edit-2
        1 year ago

        It may be difficult if the context behind those decisions are lost, but I imagine it can be doable for a smaller company, assuming the amount is reasonable. And ofc, there’s always a chance the extra overhead may piss off a few engineers 😆

    • canpolatOP
      link
      fedilink
      English
      arrow-up
      2
      ·
      1 year ago

      That sounds like you have slightly deviated from the simple ADR format (maybe not)? How do you perform the voting?

      • mark
        link
        fedilink
        English
        arrow-up
        3
        ·
        edit-2
        1 year ago

        We just thumbs up the PR for an ADR if we’re in favor of it. Does that differ from the ADR format?

        • canpolatOP
          link
          fedilink
          English
          arrow-up
          2
          ·
          1 year ago

          I see. I guess if it’s accepted then you update the Status in the PR and merge it? There isn’t a single ADR format; there are several ADR formats that are successfully being used by different teams. The format I had in mind was the one introduced by Nygard (linked article). In our case, we generally first discuss the topic and then write the accepted decision in an ADR. So, there isn’t much room for discussion/voting afterwards.

          But it’s good to learn about other people using it in different ways (a learning opportunity for me). It’s interesting that you mention ADRs stopping people from refactoring. Do you have any examples you could give?

          • mark
            link
            fedilink
            English
            arrow-up
            2
            ·
            1 year ago

            we generally first discuss the topic and then write the accepted decision in an ADR. So, there isn’t much room for discussion/voting afterwards.

            This makes sense. I guess it would cut down on the noise in the PR since, at the point of its creation, it’s already been accepted. Our repos have so many other teams contributing to them that it’s hard to rally everyone to build consensus on an ADR beforehand. I guess we could hold meetings, but having feedback in a PR allows us to go back and look at what discussions led to a decision later on.

            How does your team build consensus before opening the PR? Is it through slack or some other chat tool? Or maybe a meeting?

            • canpolatOP
              link
              fedilink
              English
              arrow-up
              2
              ·
              1 year ago

              We do that in a meeting. In some cases it may take several meetings before we can make a decision. But I think those are generally fruitful meetings (I don’t see them as waste of time). PRs give people a chance to think about these on their own pace, but when it comes to decision making, I feel like meetings actually save time (provided that people are sufficiently informed).

              It’s also possible that our ADRs deal with higher level decisions and is therefore easier to establish some sort of a consensus. From your description (especially the “refactoring” bit) I thought maybe you are using ADRs at a level that is closer to code. I cannot really think of our ADRs stopping people from refactoring the code in any way :)

              • mark
                link
                fedilink
                English
                arrow-up
                3
                ·
                1 year ago

                The meetings approach is interesting. I think we did those for RFCs but I remember they were very very long and unproductive. I think the company size matters when determining the right approach.

  • nibblebitA
    link
    fedilink
    English
    arrow-up
    5
    ·
    1 year ago

    We use them. They have been incredibly helpful. The concept has spread to our product team making product decisions!

    • canpolatOP
      link
      fedilink
      English
      arrow-up
      2
      ·
      1 year ago

      We started with with ADR, but then we also started using RFCs to discuss designs. Having this sort of minimal documentation really helps us in many aspects.

  • Dave Copeland
    link
    fedilink
    English
    arrow-up
    5
    ·
    1 year ago

    We used this at my last company. We backported decisions into them as documentation. People sometimes referred to them, but not often. It was hard to take what was a huge list of docs, some of which had been obviated by others, and truly grok them all. But I don’t have a better idea for how to solve the problem. I would say it worked OK, but not great.

  • douglasg14b
    link
    fedilink
    English
    arrow-up
    4
    ·
    1 year ago

    This is the kinda stuff I expect to find in this kind of community! ADRs are a good topic that can help teams act more mature.

    And less general career questions and low-level “what technology should I learn” 🤔

  • Amuck7157@lemm.ee
    link
    fedilink
    English
    arrow-up
    3
    ·
    1 year ago

    This is interesting! I think conceptually we’ve tried stuff like this but never had a standard to point to. I think it also helps figuring out when and why a decision was made even if you are an “expert”, as we all forget

  • mattburkedev
    link
    fedilink
    English
    arrow-up
    2
    ·
    1 year ago

    I like them a lot. Sometimes I use it as an agenda to sell an idea in a meeting. Othertimes I backport them after a decision has been made. It’s the context that drives a decision that easily gets lost to time.

    I’ve been burned when a technical decision hurt us down the road and no one could really remember why we made it to begin with.

    • canpolatOP
      link
      fedilink
      English
      arrow-up
      2
      ·
      edit-2
      1 year ago

      The post is what started the whole ADR wave in the industry (I think there was also a conference talk by him). https://adr.github.io/ has a list of resources (templates, articles, examples, tools, etc.).