On 12/5/23 1:43 AM, boost-request@lists.boost.org wrote:

Date: Mon, 4 Dec 2023 12:36:27 -0800 From: Marshall Clow To: boost@lists.boost.org Subject: Re: [boost] The standard library is better documented Message-ID: Content-Type: text/plain; charset=utf-8 On Dec 4, 2023, at 12:21 PM, Mateusz Loskot via Boost wrote:

...

On Mon, 4 Dec 2023 at 21:05, Niilo Huovila via Boost mailto:boost@lists.boost.org> wrote:

...

...

...

On 2. Dec 2023, at 16:57, Ren? Ferdinand Rivera Morell via Boost 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

On 12/4/23 4:36 PM, Hans Dembinski wrote: 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 To:boost@lists.boost.org Subject: Re: [boost] The standard library is better documented Message-ID:<9e217656-9b05-4e82-a5a3-67c55d949b4f@gmail.com> Content-Type: text/plain; charset=UTF-8

On 12/4/23 20:53, Niilo Huovila via Boost wrote:

...

...

...

On 2. Dec 2023, at 16:57, Ren? Ferdinand Rivera Morell via Boost 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

On 12/4/23 4:36 PM, Hans Dembinski wrote: 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.