Recommendations for documentation authors

From: Andrzej Krzemienski (akrzemi1_at_[hidden])
Date: 2024-01-02 08:55:30

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-guidelines.html
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;