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