The documentation has severe issues with diagrams in general, today. There is no standard way yet to do it. We have all kinds of ways to do diagrams, resulting in an inconsistent look for the documentation. I think it deserves its own discussion/PIP/issue.
Regardless, I think it's part of a PIP to add documentation to describe the feature. On Wed, May 10, 2023 at 3:58 PM Dave Fisher <wave4d...@comcast.net> wrote: > > > Sent from my iPhone > > > On May 10, 2023, at 12:01 AM, Asaf Mesika <asaf.mes...@gmail.com> wrote: > > > > On Tue, May 9, 2023 at 8:03 PM Dave Fisher <w...@apache.org> wrote: > > > >> > >> > >>>> On May 9, 2023, at 5:47 AM, Asaf Mesika <asaf.mes...@gmail.com> > wrote: > >>> > >>>> On Tue, May 9, 2023 at 5:18 AM Hang Chen <chenh...@apache.org> wrote: > >>> > >>>> Thanks for driving this discussion. > >>>> > >>>> I agree to change the proposal discussion from issue and dev mail list > >>>> to PR. It will be easier to review and comment, especially for large > >>>> proposals. > >>>> I have two questions about this change. > >>>> - Some proposals contain images, and putting those images into Pulsar > >>>> main repo will make the git db large. What's more, some images can be > >>>> up to several MBs > >>>> > >>> > >>> That's a great point, and we must address it in the PIP. > >>> How about we say that you only use: > >>> 1. Mermaid <https://mermaid.js.org/#/> - it's a tiny language to > create > >>> drawings? GitHub supports this language on code highlight and renders > it > >>> correctly. > >> > >> Does Docusaurus support Mermaid? The design documents for a PIP should > be > >> available for easy inclusion in pulsar-site. > >> > > > > Do we have plans to have a section dedicated to displays PIPs on the > > website ? > > We should make sure it is easy to convert a PIP into user documentation of > what is finally merged. > > Best, > Dave > > > > > >> > >>> 2. Use SVG files which will be located in a folder named after the pip > >>> issue number. SVG are vector graphics saved as text. For diagrams, > >>> they should be ok in size, and compress well. > >>> > >>> I think Mermaid should be enough for all drawings needed for > illustration > >>> of design document purposes. WDYT? > >> > >> I think that any reasonable format should be OK, but easily editable > >> versions should be preferred. All modern tools ought to be able to > export > >> SVG and all modern browsers render them. > >> > >> Best, > >> Dave > >> > >>> > >>> > >>> > >>>> - After merging one proposal, if we want to update the content, do we > >>>> need to discuss it in the dev mail list or just push one PR to update > >>>> it? > >>>> > >>> > >>> Does it happen often? > >>> I guess if the change is not big, it's ok just to do PR. > >>> > >>> I can clarify that as well, if it is agreed upon. > >>> > >>> > >>>> > >>>> Thanks, > >>>> Hang > >>>> > >>>> > >>>> PengHui Li <peng...@apache.org> 于2023年5月8日周一 18:06写道： > >>>>> > >>>>> Thanks for driving the improvements in proposal managing and > reviewing. > >>>>> The proposal looks good to me. I have only one question about the dir > >>>> name > >>>>> for the pips. > >>>>> > >>>>> For now, we have > >>>> https://github.com/apache/pulsar/tree/master/wiki/proposals > >>>>> Is it better to use the existing one? Or change the existing one to > >>>> "pip". > >>>>> I mean, we'd better don't use two dirs for proposals. > >>>>> > >>>>> Thanks, > >>>>> Penghui > >>>>> > >>>>> On Sun, May 7, 2023 at 5:52 PM Asaf Mesika <asaf.mes...@gmail.com> > >>>> wrote: > >>>>> > >>>>>> Ping, in case it was lost in the barrage of mails > >>>>>> > >>>>>> On Sun, Apr 30, 2023 at 10:38 AM Asaf Mesika <asaf.mes...@gmail.com > > > >>>>>> wrote: > >>>>>> > >>>>>>> Hi, > >>>>>>> > >>>>>>> I've summarized all comments from > >>>>>>> https://lists.apache.org/thread/5kpddlfh5xdbsjmv47ymnk3z6wd92jbh > >>>> into a > >>>>>>> PIP. > >>>>>>> > >>>>>>> PIP: https://github.com/apache/pulsar/issues/20207 > >>>>>>> <https://github.com/apache/pulsar/issues/20207> > >>>>>>> > >>>>>>> I'm leaving this discussion open for 2-3 days to make sure I > haven't > >>>>>>> missed a comment, and proceed to vote, since we had most of the > >>>>>> discussion > >>>>>>> already in the link provided above. > >>>>>>> > >>>>>>> Thanks! > >>>>>>> > >>>>>>> Asaf > >>>>>>> > >>>>>> > >>>> > >> > >> > >
