Oh hello! I've only been tooling about in this repo for a day or two now (prompted in part by a tweet from @bnb; though in honesty, I'm always looking to help where I can). If this is the wrong approach for some reason, I'm always open to feedback.

While exploring some of the issues and current pull requests, I've noticed a couple of architecture related discussions already cropping up. I wonder if maintainers would be interested in implementing some form of LADR going forward to document decisions made that impact general site architecture. The benefit to clear and concise documentation of previous architectural decisions is that everybody spends less time looking up or debating project context.

I only bring this up is because of my own experience with various front-end stacks. I know there are potential pros and cons to just about every solution, and the goal-posts tend to move fast. But that means client side code also tends to be hotly debated. I truly believe any architecture decision made to this point was made with the best of intentions, using the breadth of information available at that time. But I also think it's important to preserve and document this intent so that future iterations can offer informed solutions to new challenges that may arise.

Definition

LADR: Lightweight Architectural Decision Record

An Architectural Decision (AD) is a software design choice that addresses a functional or non-functional requirement that is architecturally significant. An Architecturally Significant Requirement (ASR) is a requirement that has a measurable effect on a software system’s architecture and quality. An Architectural Decision Record (ADR) captures a single AD, such as often done when writing personal notes or meeting minutes; the collection of ADRs created and maintained in a project constitute its decision log.

The ADR organization on github has a good set of documentation that outlines some of the potential templates folks might use. https://adr.github.io/

Example Architecture Questions:

This is just a short sampling of what I've seen in the last couple of days. Client-side stacks always have a lot of this sort of debate, so it's ideal to plan for it...

• Was there a specific reason for [...] choosing to use Gatsby?
• Which format should we unify around for styling?
• How do we create a preview deploy? (nobody asked this directly, but the method of triggering it does seem to be changing, and it might be nice to document how all this works)

Why would we do this?

"All the context about our current set of architectural decisions has been discussed ad nausea already and should be self evident to anyone participating in the project." (~said no one ever, I hope?)

I'm not necessarily suggesting we document every answer to every decision ever made on the project (unless they truly become the sort of content you'd add to a frequently asked questions). But as architecture shifts, or roles change, it can be valuable to include a little additional context to why or how a previous solution was found. The proposal is to pick this approach up as we move forward. It's the foundation upon which future architects can propose informed improvements.

Next Steps

If this is something we're interesting in pursuing, I'd potentially suggest creating a directory for decision records (/LADR/) and adding the inaugural decision record capturing our intent: 000-Use-Decision-Records.md.

From there, it should become policy or preference that when a new architecture decision is made (such as "using one solution over another for styling"), that it be documented with an LADR entry (to update or supersede a previous decision). We can update documentation, or simply push for them when necessary. When future discussions arise as to whether some new alternate technology is better for any use case, we can point to existing decision records that might provide useful context and hopefully eliminate unnecessary bike-shedding.