Re: The standard library is better documented

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

On Sat, Dec 2, 2023 at 2:26 PM 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. 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.

To answer my own query.. The new website has a fairly good
documentation tutorial section
<https://www.preview.boost.org/doc/contributor-guide/docs/documentation-guidelines.html>.

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