I am willing to contribute to this great initiative! On Fri, Apr 24, 2020 at 8:43 PM Joshua McKenzie <jmcken...@apache.org> wrote:
> I'm in favor of encouraging low friction / easy doc contributions by using > generally accepted simple formats (i.e. markdown). Also, if any change in > doc framework or tooling would ease adoption of donation + prevent re-work, > that'd be an obvious benefit to deciding on that prior. > > On Fri, Apr 24, 2020 at 4:19 PM Sylvain Lebresne <lebre...@gmail.com> > wrote: > > > > Are there any questions or concerns about this donation? > > > > Getting substantial contributions to the documentation is a great thing > to > > me > > in principle. > > > > My main question was around the exact form this donation would take since > > the > > project has already lots of documentation. And I was about to suggest > that > > a > > good option would be individual tickets to contribute specific additions > to > > existing parts and probably a few new parts. But your last email suggests > > exactly this from what I understand, so I'm personally satisfied on that > > front. > > > > > Any thoughts on documentation system to use long-term, since a donation > > > of this size would be a reasonable time to consider switching to > > something > > > more preferable > > > > My advise would be to ignore that consideration from the process of such > > contribution. I don't think the impact is that big, and my experience is > > that > > such "only-semi-related" dependencies often needlessly slows the > > contribution > > process for little benefit. > > > > To justify this a bit, my reasoning is that assuming we do change the > > existing > > system, given our usual process for contributions works better with > > text-based > > things, then it's hard for me to imagine a strong argument made for > moving > > out > > of a somewhat standard markup format (but I'd welcome good arguments that > > proves me wrong). > > > > So it would be a change from one "somewhat standard markup format" to > > another, > > and those have tools to convert between each other (pandoc > > (https://pandoc.org/) comes to mind, and while I think its rst support > is > > not > > extensive, https://pypi.org/project/sphinx-asciidoc/ is probably good > > enough). > > > > Tbc, such conversion probably need some light post-processing in > practice, > > but > > that's unlikely a huge undertaking, even with significantly more > > documentation > > than the project currently has. > > > > > I'd like to get the docs out of Sphinx. I hate it. The syntax is crap > > and > > > almost nobody knows it. > > > > > As a stopgap, Sphinx can generate docs based on markdown (and possibly > > even > > > asciidoc but I haven't checked). Probably easiest to do the conversion > > to > > > markdown incrementally that way, then we can flip everything over to > > Hugo. > > > > I respect your opinions, but before considering such change "acted", I > > would > > hope that (as for anything else) a case with as-objective-as-possible > > arguments > > is made. One that weights the benefits against its costs. > > > > Tbc, it's not that I care deeply for either Sphinx or reStructuredText > on a > > personal level, nor that I'm opposing such changes on principle. Just > that > > the ROI is not _that_ obvious to me, in that while I can see some pros, I > > don't > > find them overwhelming and I do see some cons (this needs a longer > > discussion, > > but to mention just one of the top of my head: the > > CQL reference doc does use 'grammar' conveniences and that is imo > genuinely > > nice (for users using the doc) but might be a PITA to reproduce with > > asciidoc/markown). > > > -- Thanks, Tajinder
