Re: The standard library is better documented

From: René Ferdinand Rivera Morell (grafikrobot_at_[hidden])
Date: 2023-12-02 20:26:34

On Sat, Dec 2, 2023 at 1:12 PM Mateusz Loskot via Boost
<boost_at_[hidden]> wrote:
>
> On Sat, 2 Dec 2023 at 16:58, René Ferdinand Rivera Morell via Boost
> <boost_at_[hidden]> wrote:
> > On Sat, Dec 2, 2023 at 2:08 AM Niilo Huovila via Boost <boost_at_[hidden]> wrote:
> > >
> > > By better I mean cppreference.com. There's a page for pretty much
> > > everything in the standard library. Related pages are linked. The
> > > preconditions and behavior of functions are specified. Consequentially I
> > > come to Boost only when the standard library doesn't do enough. If you
> > > are going to compete with the standard library instead of just
> > > supplementing it, you need outstanding documentation.
> >
> > It would be useful if you could point to instances of Boost libraries
> > that could use better documentation.
>
> I can point to such instances: all Boost libraries.
>
> I do realise I may sound cynical, but as a user I've been tolerant
> to the Boost authors' freedom of choice for very long time,
> enough to make me feel entitled to express it that way.
>
> Of course, this applies to myself, who's old school punk nature once
> raised again with "Hmm, what is the documentation tool that
> Boost has *not* seen yet?" which turned into forcing GIL to Sphinx.
>
> My autistic mind literally suffers from all of the freedoms allowed in
> Boost leading to inconsistent mess of tools, source formatting,
> markup formats and rendering results.
>
> Lately, I've had to be Go'ing a lot and it's been like a cucumber
> compress to vigilant eyes of the "death march" coder.

Having lived through the variety of documentation tools Boost has used
(being the Documentation Manager for some years) I can honestly say
that the principal problems are not in the tooling. Hence why I asked
which libraries the OP thought were a problem. IMO programmers find it
difficult to compose documentation. Never mind writing high quality
and consistent documentation. And to make it worse we provide
essentially zero guidance
(https://www.boost.org/development/requirements.html#Documentation)
and help for new contributors. I think it would be useful to have a
detailed tutorial and reference that provides authors with a framework
as to what good Boost documentation should look like. Having that we
could do a better job of evaluating new submissions and improving
existing documentation towards a high quality target.

-- 
-- René Ferdinand Rivera Morell
-- Don't Assume Anything  -- No Supone Nada
-- Robot Dreams - http://robot-dreams.net