I think those are two sides of the documentation story. ADRs might document choices before you can even think of implementation or prepare user documentation. A lot of documentation cannot be written until the UI is prepared and particular commands are executed.
ADRs usually capture the "intent" whereas user documentation captures the "execution of that intent". I highly doubt you can write good user documentation before you implement the feature - but you can definitely write a good ADR. Then, as you advance the implementation, periodically turn the ADR into user documentation. For me both are needed and both should be synced. ADR should be available before you start implementation and User docs should appear during implementation, turning the ADR into user documentation for what has been already implemented. This documents the conversion of "intent" into "implementation". And "intent" is even more important than user documentation in AI world, because if you have the intent and keep it updated while you develop, then you can genearate implementation from the "ADR" (intent) and then generate the user documentation from the implementation. Some people are even saying that in the future, we will only keep the intents (i.e., the ADR document) in whatever replaces GitHub. The code, deployment, and user documentation will be ephemeral artifacts that exist only as long as the intent remains unchanged. This is what I am talking about: the GitHub creator is now working on this concept: https://www.geekwire.com/2026/former-github-ceo-launches-new-developer-platform-with-huge-60m-seed-round/ I am personally not as "forward" as as Thomas is - and I still think GitHub (and git) is still great to keep all of that: * intent (ADR) * code * user docs All should stay in the same repo, IMHO, so that humans and agents to be able to: a) Verify consistency between the intent, code, and user documentation. b) Fix the consistency as needed c) If we change the intent, re-run the process starting from the intent through the code and documentation cycle. I think THAT is the future. J. On Sat, Apr 25, 2026 at 5:18 PM Elad Kalif <[email protected]> wrote: > Thanks for the points raised. > I am not sure about the ADR approach. The ADR documentation is for > developers - it is not user facing documentation and it's more to explain > why a design choice was made. > I don't think this is the problem we want to solve. The problem we > discussed is that user facing docs are coming too late on the development > cycle and very close to the release date. > > On Wed, Apr 22, 2026 at 11:09 PM Buğra Öztürk <[email protected]> > wrote: > > > Thanks Elad! I think it is a great idea! Both the ADR and the > document-only > > process can work in combination as well. If we had a template (e.g., > > headings, what to write, and overall technical direction), it would be a > > great combination with the document-first approach. It also feels like a > > waterfall approach if we go into too much technical detail with AIP or > > AIP+ADR. Even though currently the AIP should define boundaries and > > definitions from the start (requirement gathering, collecting feedback > and > > shaping the AIP), technical evolution is like a spiral or incremental > async > > model, which evolves. It would be great if we didn't lose that velocity > > The proposal also contains good exit points in a non-mandatory fashion. > > I think we should also (like Jarek suggested) have agent and ai related > > templates that we fill and guide contributors who use agents > > Small note, I am not trying to say any of these should be mandatory. I > > mean, just combining some of them and scoping the details we need to > share > > or consume could work better > > > > Bugra Ozturk > > Kind regards, > > > > On Sun, Apr 19, 2026 at 4:52 PM Jake McGrath via dev < > > [email protected]> > > wrote: > > > > > As someone navigating the AIP process for the first time, I’d also +1 > > > this. Throughout the process, scope has changed, new features have been > > > released, and additional (supplemental in my case) AIP’s have been > > created. > > > There has been a good bit of feedback, thoughts, and changes, but not a > > > great place for these to live. Definitely think that a framework like > > this > > > would be quite helpful! > > > > > > Jake > > > > > > > > > On Apr 15, 2026 at 11:02:05 AM, Jarek Potiuk <[email protected]> wrote: > > > > > > > +1.With some (I think) pragmatic twist proposal. > > > > > > > > I would even propose a little more organized step between the AIP and > > > > implementation starts (especially with regards to the "first" in the > > > title) > > > > that when we decide to implement something, the first step is to > create > > > an > > > > ADR (Architecture Decision Record) [1] capturing the most important > > > > decisions. Capture it semi-automatically from the discussions, AIP > doc, > > > > comments etc. and store it in the repository before we create user > > > > documentation. It should be our "Anchor" of the implementation work. > > > > > > > > In short it should explain, why we are doing it, what options we > > > considered > > > > (and discarded, including the reasons why), what the consequences are > > > > (i.e., the ripple-effect of the change and which areas are impacted), > > and > > > > of course link to the AIP for details. Also, include information > about > > > what > > > > User Documentation should be created as part of the implementation. I > > > think > > > > creating user documentation "beforehand" the code and feature it > > > implements > > > > is extremely difficult; it's much easier to decide before what kind > of > > > > documentation needs updating and then keep updating the docs while > > > > developing the features - especially when using Agentic assistance. > > > > > > > > With the agentic framework, those kinds of thoughts and discussions > > > should > > > > be captured as close to the code as possible. This ensures that > agents > > > > implementing features find them right where they are needed and that > > > these > > > > discussions serve as authoritative sources for the "scope" and > > "feature" > > > to > > > > implement. And if we add to our AGENTS.MD: "Always update the > > > documentation > > > > when you implement or change Airflow features." The agents will > > generally > > > > just **do it** by looking at the code being submitted and reading > what > > it > > > > does. I've been testing it recently on pr-auto-triage and it works > > really > > > > well as a workflow. > > > > > > > > We are increasingly describing what we want and why in plain > > English—not > > > > how we do it. Keeping records of these decisions seems really > important > > > > because the code we produce becomes more of a by-product. If we keep > > such > > > > records we can generally regenerate or optimize parts of the code > once > > we > > > > know what we are doing and why, and have that information recorded. > > > > > > > > I also have old ADRs for Breeze [2] which I created when we rewrote > > > Breeze > > > > in Python. These ADRs show what it can be, but they can now be much > > > better. > > > > We just point agent at the AIP - ask to summarize, review and agree > on > > it > > > > (which is an important step to void all kinds of ambiguties and size > of > > > > AIPs). ADRs are simply well structured markdown files, we could even > > add > > > > (actuially even generate from AIPs) some high-level mermaid markdown > > > charts > > > > in them and Agents are capable of handling them really well. > > > > > > > > [1] https://en.wikipedia.org/wiki/Architectural_decision > > > > [2] https://github.com/apache/airflow/tree/main/dev/breeze/doc/adr > > > > > > > > > > > > > > > > On Wed, Apr 15, 2026 at 11:40 AM Elad Kalif <[email protected]> > > wrote: > > > > > > > > Hello everyone, > > > > > > > > > > > > Following the last dev call, I'd like to open a discussion around > > > > > > > > documentation first approach. > > > > > > > > > > > > My key observations around Airflow 3.2 development cycle is that in > > order > > > > > > > > to do affective testing I need to understand how a feature designed > to > > > > > > > > work. While it is listed and explained in AIP page, dev discussions > and > > > > > > > > possibly in PR description it is not reasonable to expect community > > users > > > > > > > > to go through all of these data points. We have multiple features > that > > > are > > > > > > > > being developed in parallel so it's huge effort for community > members. > > By > > > > > > > > having documentation ready early we help community members to be able > > to > > > > > > > > efficiently test the feature in a real production-like scenario. It > > will > > > > > > > > also help us to gain valuable and early information about if users > > > > > > > > understand the feature as we intended. This avoid cases where > > > documentation > > > > > > > > lands around/after beta release is cut leaving little time to > testing. > > > > > > > > > > > > Given the AI era, it might even be easier to create and update > > > > > > > > documentation as development of the feature progress - it can even > make > > > PR > > > > > > > > review easier. > > > > > > > > > > > > The Proposal: > > > > > > > > > > > > 1. The default AIP draft will include a specific entry if the author > > > thinks > > > > > > > > it should be under the Documentation first policy. I think it's > better > > to > > > > > > > > let authors choose while the community review the choice. It will > also > > > > > > > > mention by what part of the development documentation should be ready > > > > > > > > (before development. by date, by specific milestone, etc...) > > > > > > > > > > > > 2. Community will review it as part of the AIP review. > > > > > > > > > > > > 3. Request to include a feature / AIP under the policy may also come > > > after > > > > > > > > AIP was approved if circumstances justify it. This means that any > > > community > > > > > > > > member can raise the request. If the AIP author agrees then the AIP > > page > > > > > > > > will be updated accordingly. In the cases where AIP author disagree, > > the > > > > > > > > community member can raise mailing list discussion. > > > > > > > > > > > > Thanks, > > > > > > > > Elad > > > > > > > > > > > > > > > > > >
