Re: The standard library is better documented

From: Mateusz Loskot (mateusz_at_[hidden])
Date: 2023-12-03 22:50:27

On Sat, 2 Dec 2023 at 21:26, René Ferdinand Rivera Morell
<grafikrobot_at_[hidden]> wrote:
> 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.

I disagree.

> And to make it worse we provide essentially zero guidance
> (https://www.boost.org/development/requirements.html#Documentation)
> and help for new contributors.

I agree, I think.

Best regards,
-- 
Mateusz Loskot, http://mateusz.loskot.net