+1 on md over google doc. > ... Google Docs do not show up in Google searches ...
This is bad for our design docs. How about the other search engines? Ritest, thanks for bringing this up! Tsz-Wo On Tue, Apr 15, 2025 at 1:44 AM Abhishek Pal <pal.abhishek03012...@gmail.com> wrote: > 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 > > > > > > > > > > > > > > >
