Hi everyone, Great points from both sides. Confluence (cwiki) is excellent for dense discussions and inline commenting, while GitHub is much better for keeping docs close to the code to avoid context-switching.
To get the best of both worlds and avoid the common issue of "stale docs" (where actual implementation drifts from the original design), I propose a two-stage approach: 1. **Draft & Review:** Use Apache Confluence (cwiki) for the initial proposal, inline commenting, and reaching a consensus. 2. **Archive & Maintain:** Once approved, export the final design to Markdown and submit a PR to an `rfc/` (or `design-docs/`) directory in our GitHub repo. This keeps the final design living alongside our codebase. If a future PR changes the implementation, the developer can update the design doc in that exact same PR. Best, Minghuang Li On 2026/03/30 08:22:43 Jerry Shao wrote: > Hi team, > > I'm thinking of consolidating the design doc. Previously, we used issue + > gdoc to post and review the design docs. This makes the design doc split > everywhere, and not easy to find and revisit. > > I was thinking of a way to put all of them together. One way is to use > Confluence wiki to manage all the docs. Another is to create an EPIC issue > or label that can quickly find all the docs. > > Or, are there any better options? > > Best, > Jerry >
