Re: [boost] The standard library is better documented

5 Dec 2023


      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.