Re: [boost] The standard library is better documented

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. 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