Re: Recommendations for documentation authors

From: Andrey Semashev (andrey.semashev_at_[hidden])
Date: 2024-01-02 11:52:04

On 1/2/24 11:55, Andrzej Krzemienski via Boost wrote:
> 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.

To me, QuickBook is the most powerful tool for writing documentation, so
I'm not going to recommend anything new. As the changelog says, the
latest version supports direct HTML output, but I haven't tried it. I
imagine, it should work for simple docs without BoostBook/DocBook
specific features.

I think, it would be very useful to continue improving QuickBook, in
particular to support additional output formats, maybe even AsciiDoc. We
have lots of documentation written in it, and new libraries use it as well.

Perhaps, if you post some details about your problems with QuickBook,
someone will be able to help.