+1 Initially I was reluctant because of the cost of converting Google Docs to Markdown.
However, worry no more! Google Docs has built-in support for Markdown! Follow the instructions in this page https://support.google.com/docs/answer/12014036?hl=en So if anyone writes an initial draft in Google Docs, it should take no time to turn it into Markdown, and then a pull request. On Mon, Apr 14, 2025 at 10:42 AM 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 >
--------------------------------------------------------------------- To unsubscribe, e-mail: dev-unsubscr...@ozone.apache.org For additional commands, e-mail: dev-h...@ozone.apache.org
