Re: [boost] The standard library is better documented

On Sat, 2 Dec 2023 at 21:26, René Ferdinand Rivera Morell wrote:

On Sat, Dec 2, 2023 at 1:12 PM Mateusz Loskot via Boost wrote:

...

On Sat, 2 Dec 2023 at 16:58, René Ferdinand Rivera Morell via Boost wrote:

...

On Sat, Dec 2, 2023 at 2:08 AM Niilo Huovila via Boost 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