Re: Recommendations for documentation authors

From: John Maddock (jz.maddock_at_[hidden])
Date: 2024-01-02 13:08:15

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

+1.