+1
Thanks, Dinesh On Mon, Apr 14, 2025, 1:42 PM Ritesh Shukla <rit...@apache.org> wrote: > Hi, > > We should shift our design discussions from Google Docs to Markdown files > managed through GitHub Pull Requests. This approach would: > > 1. Keep our discussions in the same system as our code, creating a more > cohesive history > 2. Make our design documents more accessible to developers already > familiar with our workflow > 3. Enable better version tracking and diffing through Git's native > capabilities > 4. Allow for easier integration with our existing documentation > > This shift aligns with open-source best practices and would reduce context > switching between platforms. Also, Google Docs do not show up in Google > searches and tend to get lost into obscurity. Without going into details, I > am also not sure if they can be preserved for the duration of the project > (vs a Git commit). > > Thus, if we accept this proposal any Jira with a Google Doc attached for > design would be requested to open a PR for the Jira with the design doc. > > We could use Jira, but its interface is not suitable for large texts > compared to the rich ecosystem around Markdown for authoring documents. > Most IDEs have excellent Markdown integration. > > We can draw images in our favorite editor and attach them to a markdown (or > use ASCII art). LLMs are also very capable of authoring good ASCII diagrams > or flow charts. > > Ref: > > https://github.com/apache/ozone/pull/6121 > > Regards, > > Ritesh >
