Re: [boost] The standard library is better documented

On 12/3/23 3:37 AM, boost-request@lists.boost.org wrote:

Date: Sat, 2 Dec 2023 17:44:05 +0100 From: Andrzej Krzemienski To: boost@lists.boost.org Subject: Re: [boost] The standard library is better documented Message-ID: Content-Type: text/plain; charset="UTF-8"

sob., 2 gru 2023 o 17:21 Andrey Semashev via Boost napisa?(a):

...

On 12/2/23 03:35, 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.

To be fair, as useful as cppreference.com is, it is not quite the same kind of documentation as Boost documentation is. It is mostly similar to the reference section that you can find in most libraries' docs, as it basically translates the standard wording to human language and gives a single usage example in the end. There is no rationale, discussion, or usage recommendations.

It's a feature: there's a time for discussion and rationale, but not when I just want to look up something quickly.

...

The unquestionable advantage of cppreference.com is that it has lots of cross-links, which makes it very easy to navigate and find what you're looking for. Cross-linking is definitely something that Boost docs could use more.

^ This. The easy to navigate reference is what I miss the most. Cppreference can be explored like a retailer's magazine. Items are usually sorted to categories. It makes them more discoverable.

True, but for that we would have to have a uniform documentation experience for all the libraries. And I do not think we are ever going to get there.

I agree that it's a daunting task. Actually I thought that the first reaction to my message would be pondering whether competing with the standard library is worth the effort or even feasible. I were surprised when the first reaction was asking which docs need improvement, because cppreference sets the bar so high.