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). >
