Thanks for the proposal Ritesh. I think the docs module is not as actively contributed to and it would be good to move towards adding design docs to this - as we can integrate it directly with the Ozone website as well.
This would also give users an idea of what is planned for the product roadmap from the proposals that get added ( we do have a Design Docs page in the website, but we can work towards making it a bit nicer if we are actively going to maintain these docs ) +1 On Tue, 15 Apr 2025 at 07:27, Tejaskriya Madan <tejaskriya.mad...@cloudera.com.invalid> wrote: > +1 > > Thanks, > Tejaskriya > > On Tue, 15 Apr, 2025, 07:00 Devesh Singh, <deveshsi...@cloudera.com > .invalid> > wrote: > > > +1 > > > > Thanks & Regards > > Devesh Singh > > > > > > On Tue, 15 Apr, 2025, 2:59 am Dinesh Chitlangia, <dine...@apache.org> > > wrote: > > > > > +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 > > > > > > > > > >
