Jarek my goal is to have user facing docs come early. The question of how these docs come to be (with/without ADR) is another topic. While you claim strong value (and I agree) there is also the question of review these ADRs in timely manner and other considerations. I do not think we need to force ADRs as part of the policy (at least not now) I rather to be focused on the outcome and let each author decide how they get there.
בתאריך שבת, 25 באפר׳ 2026, 23:33, מאת Jarek Potiuk <[email protected]>: > 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 > > > > > > > > > > > > > > > > > > > > > > > > >
