Re: The standard library is better documented

From: Niilo Huovila (niilo.j.huovila_at_[hidden])
Date: 2023-12-05 13:16:34

On 12/5/23 1:43 AM, boost-request_at_[hidden] wrote:
> Date: Mon, 4 Dec 2023 12:36:27 
> -0800 From: Marshall Clow <mclow.lists_at_[hidden]> To: 
> boost_at_[hidden] Subject: Re: [boost] The standard library is 
> better documented Message-ID: 
> <B135B251-3578-40CA-A9D8-34E165EE6C14_at_[hidden]> Content-Type: 
> text/plain; charset=utf-8 On Dec 4, 2023, at 12:21 PM, Mateusz Loskot 
> via Boost <boost_at_[hidden]> wrote:
>> On Mon, 4 Dec 2023 at 21:05, Niilo Huovila via Boost
>> <boost_at_[hidden]  <mailto:boost_at_[hidden]>> wrote:
>>> On 12/4/23 4:36 PM, Hans Dembinski wrote:
>>>>> On 2. Dec 2023, at 16:57, Ren? Ferdinand Rivera Morell via Boost<boost_at_[hidden]>  wrote:
>>>>>
>>>>> It would be useful if you could point to instances of Boost libraries
>>>>> that could use better documentation.
>>>> Can we organise a user poll that ranks all Boost libraries on how well documented they are?
>>>>
>>>> Might be a fun way to approach this and it provides an opportunity to create some publicity for Boost when we advertise this. I can see the news headline: "Boost devs finally respond to user cries for better docs"
>>> The secret of cppreference seems to be that it is a wiki. How about
>>> that? Users could put their energy to improving the docs instead of
>>> complaining. :)
>> Users can already do that by submitting pull requests on GitHub.
> Or, if they don?t grok Quickbook, they can open a GitHub issue and suggest better wording.

They seem relatively heavy-handed ways to add a link or correct spelling.

> Date: Tue, 5 Dec 2023 00:12:17 +0300
> From: Andrey Semashev<andrey.semashev_at_[hidden]>
> To:boost_at_[hidden]
> Subject: Re: [boost] The standard library is better documented
> Message-ID:<9e217656-9b05-4e82-a5a3-67c55d949b4f_at_[hidden]>
> Content-Type: text/plain; charset=UTF-8
> 
> On 12/4/23 20:53, Niilo Huovila via Boost wrote:
>> On 12/4/23 4:36 PM, Hans Dembinski wrote:
>>>> On 2. Dec 2023, at 16:57, Ren? Ferdinand Rivera Morell via Boost
>>>> <boost_at_[hidden]>  wrote:
>>>>
>>>> It would be useful if you could point to instances of Boost libraries
>>>> that could use better documentation.
>>> Can we organise a user poll that ranks all Boost libraries on how well
>>> documented they are?
>>>
>>> Might be a fun way to approach this and it provides an opportunity to
>>> create some publicity for Boost when we advertise this. I can see the
>>> news headline: "Boost devs finally respond to user cries for better docs"
>> The secret of cppreference seems to be that it is a wiki. How about
>> that? Users could put their energy to improving the docs instead of
>> complaining. :)
> Wiki is prone to vandalism and edit wars.
> 
> Also, aside from stylistic and wording edits, the documentation is
> supposed to be written by people who are very knowledgeable in the
> subject. Those people are likely very few, often maintainers only.
> 
> Wiki is good for "public knowledge" kind of documentation. The official
> library documentation is very different from that. In fact, it is the
> ground truth upon which that public knowledge is built.

Would separating the reference from other documentation also separate it 
from those concerns? Then it could be a wiki and editing the other stuff 
can be restricted to maintainers.