Hi Yufei, I agree with your points and appreciate the collaborative, user-friendly nature of Google Docs.
We can certainly continue using Google Docs during the drafting and preparation phases. However, since Google Docs exists outside of the ASF infrastructure, we should ensure the final versions of proposals are exported to and stored in our repository. This ensures they are properly archived within the ASF-managed source system (remember that GitHub is a mirror of GitBox which is ASF managed source repository). I suggest we remain flexible to encourage as many contributions as possible: 1. If a contributor prefers Google Docs for drafting and review, that works well. The document can then be exported to the website once it reaches a "final" stage. 2. If a contributor prefers to submit a proposal via a Pull Request in Markdown, that is also acceptable. If there are no objections, I would like to experiment with the Markdown approach for the Delegation Services proposal. What do you think? Regards, JB On Tue, Feb 17, 2026 at 7:55 PM Yufei Gu <[email protected]> wrote: > Hi all, > > In my experience, Google Docs works very well for design discussions. The > real time collaboration, quick iteration, and low barrier to editing make > it much easier to shape ideas, especially in the early stages. Multiple > people can work on a single Google Doc seamlessly, whereas coordinating > edits across one PR with several contributors is not as straightforward. > Diagrams are often an important part of proposal discussions. Adding, > editing, and iterating on diagrams is much easier in Google Docs. In a PR > workflow, updating diagrams usually requires external tools, and new > commits, which slows down iteration. > > The PR review process also works differently from open design exploration. > Long discussions can quickly accumulate dozens of comments, making the page > slower and harder to navigate. You've probably experienced slow GitHub PR > pages when there are 80+ comments. And we would likely need additional > rules around approvals or change requests for proposal docs, which adds > more process overhead. > > I believe Google Docs should remain a valid and practical option for > drafting and collaborative design discussions. I'd love to still keep that > option. > > Yufei > > > On Tue, Feb 17, 2026 at 10:26 AM Dmitri Bourlatchkov <[email protected]> > wrote: > > > Hi Robert, > > > > Excellent idea about leveraging the PR review process for proposal docs! > > > > I'm not sure we need to spend extra effort to publish proposals on the > main > > site (unless it is easy :) ) as long as the contribution guide is clear > > about how to find them in GH. > > > > Once a proposal is implemented, the docs will naturally be updated with > > corresponding user-facing instructions. > > > > Cheers, > > Dmitri. > > > > On Sun, Feb 15, 2026 at 8:41 AM Robert Stupp <[email protected]> wrote: > > > > > Hi all, > > > > > > Mick brought up a very good point [1] about the use of Google Docs for > > > proposals. > > > > > > Very simplified, our current proposal process is > > > - a contributor creates a Google Doc > > > - the proposal is introduced on [email protected] > > > - discussion happens on both the Google Doc and the dev@ mailing lists > > > > > > Google Docs are a great vehicle for collaboration. Just, I think the > > > commentary functionality there is a bit odd. > > > There's also a "disconnect" (or "media break" if you prefer that term) > > > between the discussions that actually count and those that do not > (think: > > > "If it did not happen on the mailing list, it never happened.") > > > The valuable information in those Google Docs gets "lost", as there's > no > > > more direct relationship from the code or documentation to a proposal > and > > > the discussion that happened on it. > > > > > > We currently do not have a consistent overview of all proposals, the > > > activity on those and their status. > > > > > > Technically speaking, proposals could fit pretty well into the GitHub > > > pull-request workflow and, once accepted, serve as a reference, provide > > > insight into the agreed on ideas or even serve as documentation. > > > > > > What I am thinking of is a space on the web site that: > > > * lists the current proposals built from a query against open PRs with > > e.g. > > > the 'proposal' label, > > > * lists of closed proposals, closed PRs (dropped ideas or approaches), > > > * list of accepted proposals, merged PRs > > > > > > Moving proposals to PRs containing markdown (or asciidoc), would close > > the > > > "media break" and fix nicely with "it happened on the mailing list." > > > > > > I'd like to not go into the technical details or where the proposals > > would > > > live in this discussion, but rather get your thoughts about the idea in > > > general. > > > Just so much: GitHub has a good edit functionality with a live markdown > > > preview as a split view [2]. > > > > > > Cheers, > > > Robert > > > > > > > > > [1] https://lists.apache.org/thread/dnvfck8owpz0z1n1f93mnjm2nlcjp3ym > > > [2] https://github.dev/apache/polaris/blob/main/README.md > > > > > >
