Re: The standard library is better documented

From: Niilo Huovila (niilo.j.huovila_at_[hidden])
Date: 2023-12-03 21:02:33

On 12/3/23 3:37 AM, boost-request_at_[hidden] wrote:
> Date: Sat, 2 Dec 2023 17:44:05 +0100
> From: Andrzej Krzemienski <akrzemi1_at_[hidden]>
> To: boost_at_[hidden]
> Subject: Re: [boost] The standard library is better documented
> Message-ID:
> 	<CAOenAXhr9fu6jo7PoFC6JTKBhD7Kdw6yxWJUEFxtcPgYkujHwQ_at_[hidden]>
> Content-Type: text/plain; charset="UTF-8"
> 
> sob., 2 gru 2023 o 17:21 Andrey Semashev via Boost <boost_at_[hidden]>
> 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.