Hi Boost Developers, And a happy New Year (at least for those who recognize the Gregorian calendar). While I consider improving the documentation quality of some Boost libraries, I wonder if there are any tool or workflow recommendations for the library authors regarding the documentation. I know we do not force any specific tool or format, so I am only asking about recommendations. I note that page https://www.preview.boost.org has at https://www.preview.boost.org/doc/contributor-guide/docs/documentation-guide... the following:
The format for documentation on the new website is AsciiDoc Syntax Quick Reference https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/.
Should I treat it as a recommendation to use AsciiDoc? I note that quite a few new libraries choose it. I also see the advantage: you need no special tool for it: a simple web browser knows how to format it. But I found the documentation of libraries that use adoc to be uncomfortable to read. I do not know if this is the tool itself or maybe the correlation between the choice of the tool and the devotion to documentation quality, or maybe something else. It is quite subjective. The older libraries' documentation (using BoostDoc) seemed more friendly and easier to navigate. But to write and maintain such documentation is a challenge. Last year something broke in my pipeline (QuickDoc, xstlproc) and to this day I am not able to determine what it is. So, relying on too complex flows, which become obsolete over time, also doesn't seem like a good idea. I wonder if any of you have similar thoughts, and if you can recommend something for writing good quality and user friendly documentation. Regards, &rzej;