Re: Recommendations for documentation authors

From: Andrzej Krzemienski (akrzemi1_at_[hidden])
Date: 2024-01-03 08:01:07

wt., 2 sty 2024 o 17:00 Vinnie Falco <vinnie.falco_at_[hidden]> napisał(a):

> On Tue, Jan 2, 2024 at 12:55 AM Andrzej Krzemienski via Boost <
> boost_at_[hidden]> wrote:
>
>> 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.
>
>
[snip]

Now here is one datapoint which pretty much speaks for itself:
>
> Peter Dimov and René Ferdinand Rivera Morell use Asciidoctor (
> https://asciidoctor.org/).
>
> I can't stand the default asciidoc templates, but I have to say that this
> tool is not only well maintained but it is incredibly popular and only
> becoming moreso. The authors and contributors have an active messaging
> forum and Discord chat server. It is used across a variety of programming
> languages. GitHub automatically previews Asciidoc files:
>
> https://github.com/boostorg/url/blob/develop/README.adoc
>
> The same cannot be said for Quickbook, Boostbook, or Docbook.
>
> Not only is Asciidoctor a great markup language and tool but the authors
> have also built a document management system on top of it called Antora:
>
> https://docs.antora.org/antora/latest/
>
> In terms of best practices, I suggest the following:
>
> * Use Asciidoc markdown (.adoc files) for documentation
> * Run asciidoctor to turn .adoc files into HTML
> * Use Antora if you want to use the best features in your documentation
> (such as cross-library documentation linking)
>
> The only thing left is a Doxygen-equivalent tool to extract javadoc
> comments from C++ code and turn it into Asciidoc markdown. The C++ Alliance
> is working on this tool. I started the project, and now Krystian Stasiowski
> is the principal engineer. Check out the #mrdocs in the Official C++
> Language Slack Workspace (https://cppalliance.org/slack/). The website
> for mrdocs is here (work in progress):
>
> https://mrdocs.com/
>

So at least conceptually, QuickBook->BoostBook flow is doing the same thing
as Aciidoc.
I also guess that, at least conceptually, the Asciidoc can be made to
render as clear and aesthetic output as the QuickBook->BoostBook flow.
But for now, it is not true. Do there exist other ready-to-use templates
for asciidoctor that would return output suitable for software
documentation?
I am not satisfied with the present effect of Boost Libraries that choose
to use AsciiDoctor for documentation. There may be different causes.

Here is a work in progress demo of the Boost.URL library reference rendered
> in asciidoctor with Mr. Docs:
>
>
> https://mrdocs.com/demos/develop/boost-url/multi/adoc-asciidoc/boost/urls.html
>

I understand that it is work in progress as for now. I am not satisfied
with the present result. Take `pct_encoded_rule_t` for instance. It is
listed as "type", but it is actually an alias template whose *role* is to
be a *meta-function*. Users need to know about it. This classification into
namespaces/types/functions/enums/variables is insufficient for C++. For
instance we use classes as *tags* (like std::in_place_t) and this is
something different than using classes for maintaining an invariant.
There are those cases from Boost.Beast when class X implements function
X::f(), as required by the concept, but it does so via derivation. But we
want to keep the fact of deriving as an implementation detail not exposed
in the documentation.

I remember complaining about this to the author, and got a reply "I
acknowledge that this is an inconvenience but I am confined to the tool
that I am using".

I do not know how much additional markup you have to invent to achieve a
satisfactory state.

> And here is the recent Boost.Scope library documentation rendered using
> Mr. Docs:
>
>
> https://mrdocs.com/demos/develop/boost-scope/multi/adoc-asciidoc/boost/scope.html
>

While I appreciate the amount of work that went into it, I must say I am
not satisfied with the result. Sometimes it boils down to how cautious the
author is about putting their annotations, but because the annotations are
in the code, the author doesn't have the picture of how they will appear in
the context of the documentation. We end up with the situation as in
https://mrdocs.com/demos/develop/boost-scope/multi/adoc-asciidoc/boost/scope/error_code_checker.html
Where I need to click on type `result_type` only to learn on a separate
page that it is `bool`.

wt., 2 sty 2024 o 21:16 Robert Ramey via Boost <boost_at_[hidden]>
napisał(a):

>
> I here's my story with boost documentation tools.  I've described my
> views on documentation content elsewhere:
>
> https://www.youtube.com/watch?v=YxmdCxX9dMk
>
> I always liked the xml approach of separating document content from
> document rendering.  This permits one to create the content one time and
> render it according to one's desire at the time.  Thus one can produce
> HTML, PDF, (probably AsciiDoc) and who knows what else.  One could also
> create an xmlsltproc file which would automatically generate a global
> table of contents for one or all boost libraries - though this has never
> been done.  It also permitted the creating of custom "vocabularies"
> which would specify more meta data about the content.  Doug Gregor
> created all this in BoostBook but it hasn't been exploited much if any.

The idea to separate contents from the rendering is a sound one. I guess
the idea failed in the implementation.

For instance, I try to follow your (Robert's) advice to start the
documentation with a one-minute introduction that gives the touch and feel
of the library. This is impossible with BoostBook, because it generates the
Table Of Contents before any content, so the first thing the new user sees
is a big table of contents, and they are not aware that if they scrolled
down three screens they would get the information they need instantly.

wt., 2 sty 2024 o 21:26 Peter Dimov via Boost <boost_at_[hidden]>
napisał(a):

> Andrey Semashev wrote:
> > I'll note that there was a time when people wrote docs in raw BoostBook,
> > which is probably why QuickBook appeared in the first place. Those times
> > are long passed now.
>
> If I remember correctly, Quickbook was originally a tool that took .qbk
> markup and produced HTML, similar to Markdown/Asciidoc (which didn't
> exist.)
>
> It was later retargeted to output BoostBook in order for all Boost
> documentation to be integrated into the same "book" and in order for
> that "book" to be printable as PDF.
>
> This "book" survives here:
>
> https://www.boost.org/doc/libs/1_84_0/doc/html/libraries.html
>
> The idea of having an "integrated book" doesn't seem to have caught
> on, however, as most libraries prefer having its own "standalone"
> documentation that isn't part of the above.

I guess it made sense when Boost was considered a coherent whole. Now, it
looks like it is a "federation of unrelated libraries". Also, we seem to
have competing libraries (Statechart and MSM). Not sure why someone would
want to have one flat book for all of these.

I also note that Boost.Optional is not there, even though it uses the
QuickBook->BoostBook flow. So I guess it takes something more to qualify
for the book.

Regards,
&rzej;