Re: Recommendations for documentation authors

From: Andrzej Krzemienski (akrzemi1_at_[hidden])
Date: 2024-01-02 13:23:34

wt., 2 sty 2024 o 12:52 Andrey Semashev via Boost <boost_at_[hidden]>
napisał(a):

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

Thank you for the response.

So, let me give you my story, and maybe you -- or anyone else in this list
-- can give me some advice.
As probably most of us, I have only limited time to devote to Boost
maintenance. I have one library in charge that I inherited from Fernando:
Boost.Optional. I inherited a working toolchain for producing documentation
and I try not to touch it: only modify the content.
There is a Jamfile that to the initiated probably tells everything:
https://github.com/boostorg/optional/blob/develop/doc/Jamfile.v2
I do not know what it does exactly. I know it uses BoostBook and QuickBook.
It uses xsltproc indirectly, I guess.

Can I use QuickBook without a BoostBook for the Boost documentation? Is
someone doing it already?

I tried to have a look at QuickBook docs (
https://www.boost.org/doc/libs/1_84_0/doc/html/quickbook.html) and I cannot
figure out if it is a format or a tool that transforms one format into
another. I guess it is the latter, but what does it output?

How many tools do I have to learn to write documentation for a Boost
Library?

Of course, I could learn all of it. If I had unlimited time. But I only
have like a couple of hours in a week or sometimes month. I barely have
time to do the maintenance of the source code and the tests.

This is my experience, but I suppose something similar is faced by anyone
who considers proposing their libraries into Boost.

I enclose the output from my running the `b2` command in folder doc. I
would greatly appreciate it if anyone can help me fix this.

But even if this is fixed, I would still want to know why this chain of
QuickBook -> BoostBook is needed.

Regards,
&rzej;

>
>
> _______________________________________________
> Unsubscribe & other changes:
> http://lists.boost.org/mailman/listinfo.cgi/boost
>