The standard library is better documented
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.
On Sat, Dec 2, 2023 at 2:08 AM Niilo Huovila via Boost <boost@lists.boost.org> 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.
It would be useful if you could point to instances of Boost libraries that could use better documentation. -- -- René Ferdinand Rivera Morell -- Don't Assume Anything -- No Supone Nada -- Robot Dreams - http://robot-dreams.net
sob., 2 gru 2023 o 16:58 René Ferdinand Rivera Morell via Boost < boost@lists.boost.org> napisał(a):
On Sat, Dec 2, 2023 at 2:08 AM Niilo Huovila via Boost <boost@lists.boost.org> 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.
It would be useful if you could point to instances of Boost libraries that could use better documentation.
The one that I have in mind is Boost.Cobalt. I am picking on it only because we recently reviewed it, so it is fresh. Consider the documentation for cobalt::left_race: https://www.boost.org/doc/libs/1_84_0_beta1/libs/cobalt/doc/html/index.html#... Documenting it is challenging as we do not have much experience with documenting awaitables. We probably need to introduce another category apart from "Expects", "Ensures", "Returns", "Effects": something like "Await result" that describes what happens when you co_await on the returned awaitable. More on this in https://github.com/boostorg/cobalt/issues/138 Regards, &rzej;
-- -- René Ferdinand Rivera Morell -- Don't Assume Anything -- No Supone Nada -- Robot Dreams - http://robot-dreams.net
_______________________________________________ Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
On Sat, 2 Dec 2023 at 16:58, René Ferdinand Rivera Morell via Boost <boost@lists.boost.org> wrote:
On Sat, Dec 2, 2023 at 2:08 AM Niilo Huovila via Boost <boost@lists.boost.org> 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.
It would be useful if you could point to instances of Boost libraries that could use better documentation.
I can point to such instances: all Boost libraries. I do realise I may sound cynical, but as a user I've been tolerant to the Boost authors' freedom of choice for very long time, enough to make me feel entitled to express it that way. Of course, this applies to myself, who's old school punk nature once raised again with "Hmm, what is the documentation tool that Boost has *not* seen yet?" which turned into forcing GIL to Sphinx. My autistic mind literally suffers from all of the freedoms allowed in Boost leading to inconsistent mess of tools, source formatting, markup formats and rendering results. Lately, I've had to be Go'ing a lot and it's been like a cucumber compress to vigilant eyes of the "death march" coder. Best regards, -- Mateusz Loskot, http://mateusz.loskot.net
On Sat, Dec 2, 2023 at 1:12 PM Mateusz Loskot via Boost <boost@lists.boost.org> wrote:
On Sat, 2 Dec 2023 at 16:58, René Ferdinand Rivera Morell via Boost <boost@lists.boost.org> wrote:
On Sat, Dec 2, 2023 at 2:08 AM Niilo Huovila via Boost <boost@lists.boost.org> 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.
It would be useful if you could point to instances of Boost libraries that could use better documentation.
I can point to such instances: all Boost libraries.
I do realise I may sound cynical, but as a user I've been tolerant to the Boost authors' freedom of choice for very long time, enough to make me feel entitled to express it that way.
Of course, this applies to myself, who's old school punk nature once raised again with "Hmm, what is the documentation tool that Boost has *not* seen yet?" which turned into forcing GIL to Sphinx.
My autistic mind literally suffers from all of the freedoms allowed in Boost leading to inconsistent mess of tools, source formatting, markup formats and rendering results.
Lately, I've had to be Go'ing a lot and it's been like a cucumber compress to vigilant eyes of the "death march" coder.
Having lived through the variety of documentation tools Boost has used (being the Documentation Manager for some years) I can honestly say that the principal problems are not in the tooling. Hence why I asked which libraries the OP thought were a problem. IMO programmers find it difficult to compose documentation. Never mind writing high quality and consistent documentation. And to make it worse we provide essentially zero guidance (https://www.boost.org/development/requirements.html#Documentation) and help for new contributors. I think it would be useful to have a detailed tutorial and reference that provides authors with a framework as to what good Boost documentation should look like. Having that we could do a better job of evaluating new submissions and improving existing documentation towards a high quality target. -- -- René Ferdinand Rivera Morell -- Don't Assume Anything -- No Supone Nada -- Robot Dreams - http://robot-dreams.net
On Sat, Dec 2, 2023 at 2:26 PM René Ferdinand Rivera Morell <grafikrobot@gmail.com> wrote:
On Sat, Dec 2, 2023 at 1:12 PM Mateusz Loskot via Boost <boost@lists.boost.org> wrote:
On Sat, 2 Dec 2023 at 16:58, René Ferdinand Rivera Morell via Boost <boost@lists.boost.org> wrote:
On Sat, Dec 2, 2023 at 2:08 AM Niilo Huovila via Boost <boost@lists.boost.org> 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.
It would be useful if you could point to instances of Boost libraries that could use better documentation.
I can point to such instances: all Boost libraries.
I do realise I may sound cynical, but as a user I've been tolerant to the Boost authors' freedom of choice for very long time, enough to make me feel entitled to express it that way.
Of course, this applies to myself, who's old school punk nature once raised again with "Hmm, what is the documentation tool that Boost has *not* seen yet?" which turned into forcing GIL to Sphinx.
My autistic mind literally suffers from all of the freedoms allowed in Boost leading to inconsistent mess of tools, source formatting, markup formats and rendering results.
Lately, I've had to be Go'ing a lot and it's been like a cucumber compress to vigilant eyes of the "death march" coder.
Having lived through the variety of documentation tools Boost has used (being the Documentation Manager for some years) I can honestly say that the principal problems are not in the tooling. Hence why I asked which libraries the OP thought were a problem. IMO programmers find it difficult to compose documentation. Never mind writing high quality and consistent documentation. And to make it worse we provide essentially zero guidance (https://www.boost.org/development/requirements.html#Documentation) and help for new contributors. I think it would be useful to have a detailed tutorial and reference that provides authors with a framework as to what good Boost documentation should look like. Having that we could do a better job of evaluating new submissions and improving existing documentation towards a high quality target.
To answer my own query.. The new website has a fairly good documentation tutorial section <https://www.preview.boost.org/doc/contributor-guide/docs/documentation-guidelines.html>. -- -- René Ferdinand Rivera Morell -- Don't Assume Anything -- No Supone Nada -- Robot Dreams - http://robot-dreams.net
On 12/2/23 12:41 PM, René Ferdinand Rivera Morell via Boost wrote:
To answer my own query.. The new website has a fairly good documentation tutorial section <https://www.preview.boost.org/doc/contributor-guide/docs/documentation-guidelines.html>.
FWIW - I don't think this is very useful. Since the advent of templates, useful documentation has to be structured around type requirements. A quick review of the above doesn't seem to reflect this obvious fact. Robert Ramey
On Sat, Dec 2, 2023 at 12:27 PM René Ferdinand Rivera Morell via Boost < boost@lists.boost.org> wrote:
I think it would be useful to have a detailed tutorial and reference that
provides authors with a framework as to what good Boost documentation should look like. Having that we could do a better job of evaluating new submissions and improving existing documentation towards a high quality
target.
The C++ Alliance is happy to support anyone who wants to take the lead on this. Thanks
On Sat, 2 Dec 2023 at 21:26, René Ferdinand Rivera Morell <grafikrobot@gmail.com> wrote:
On Sat, Dec 2, 2023 at 1:12 PM Mateusz Loskot via Boost <boost@lists.boost.org> wrote:
On Sat, 2 Dec 2023 at 16:58, René Ferdinand Rivera Morell via Boost <boost@lists.boost.org> wrote:
On Sat, Dec 2, 2023 at 2:08 AM Niilo Huovila via Boost <boost@lists.boost.org> 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.
It would be useful if you could point to instances of Boost libraries that could use better documentation.
I can point to such instances: all Boost libraries.
I do realise I may sound cynical, but as a user I've been tolerant to the Boost authors' freedom of choice for very long time, enough to make me feel entitled to express it that way.
Of course, this applies to myself, who's old school punk nature once raised again with "Hmm, what is the documentation tool that Boost has *not* seen yet?" which turned into forcing GIL to Sphinx.
My autistic mind literally suffers from all of the freedoms allowed in Boost leading to inconsistent mess of tools, source formatting, markup formats and rendering results.
Lately, I've had to be Go'ing a lot and it's been like a cucumber compress to vigilant eyes of the "death march" coder.
Having lived through the variety of documentation tools Boost has used (being the Documentation Manager for some years) I can honestly say that the principal problems are not in the tooling.
I disagree.
And to make it worse we provide essentially zero guidance (https://www.boost.org/development/requirements.html#Documentation) and help for new contributors.
I agree, I think. Best regards, -- Mateusz Loskot, http://mateusz.loskot.net
On 2. Dec 2023, at 16:57, René Ferdinand Rivera Morell via Boost <boost@lists.boost.org> 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" I think the results would be very interesting. The top libraries on this list would then serve as examples for everyone else. We could repeat this poll in regular intervals to reward improvements in documentation. Best regards, Hans
On Mon, Dec 4, 2023 at 8:36 AM Hans Dembinski <hans.dembinski@gmail.com> wrote:
On 2. Dec 2023, at 16:57, René Ferdinand Rivera Morell via Boost <boost@lists.boost.org> 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"
I think the results would be very interesting. The top libraries on this list would then serve as examples for everyone else.
We could repeat this poll in regular intervals to reward improvements in documentation.
Sounds like a good/fun idea to me. -- -- René Ferdinand Rivera Morell -- Don't Assume Anything -- No Supone Nada -- Robot Dreams - http://robot-dreams.net
On Mon, 4 Dec 2023 at 15:36, Hans Dembinski via Boost <boost@lists.boost.org> wrote:
On 2. Dec 2023, at 16:57, René Ferdinand Rivera Morell via Boost <boost@lists.boost.org> 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? [...] We could repeat this poll in regular intervals to reward improvements in documentation.
Sounds like a good idea for fun to me too. Best regards, -- Mateusz Loskot, http://mateusz.loskot.net
On 12/4/23 4:36 PM, Hans Dembinski wrote:
On 2. Dec 2023, at 16:57, René Ferdinand Rivera Morell via Boost <boost@lists.boost.org> 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. :)
On Mon, 4 Dec 2023 at 21:05, Niilo Huovila via Boost <boost@lists.boost.org> 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@lists.boost.org> 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. Best regards. -- Mateusz Loskot, http://mateusz.loskot.net
On Dec 4, 2023, at 12:21 PM, Mateusz Loskot via Boost <boost@lists.boost.org> wrote:
On Mon, 4 Dec 2023 at 21:05, Niilo Huovila via Boost <boost@lists.boost.org <mailto:boost@lists.boost.org>> 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@lists.boost.org> 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. — Marshall
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.
Not very helpful if the pull request is ignored, e.g. https://github.com/boostorg/intrusive/pull/82. Wiki is the way to go, due to the low friction. Yes, edit wars are possible, but Boost isn't particularly prone to such type of users. Best regards, Tomer Vromen Internal Use - Confidential
On Wed, Dec 6, 2023 at 1:24 PM Vromen, Tomer via Boost <boost@lists.boost.org> wrote:
Wiki is the way to go, due to the low friction. Yes, edit wars are possible, but Boost isn't particularly prone to such type of users.
It is prone to such users (or rather bots). When we had the Trac wiki instance running, the amount of spam and corresponding filtering that we did was substantial. -- -- René Ferdinand Rivera Morell -- Don't Assume Anything -- No Supone Nada -- Robot Dreams - http://robot-dreams.net
On 06/12/2023 19:44, René Ferdinand Rivera Morell via Boost wrote:
On Wed, Dec 6, 2023 at 1:24 PM Vromen, Tomer via Boost <boost@lists.boost.org> wrote:
Wiki is the way to go, due to the low friction. Yes, edit wars are possible, but Boost isn't particularly prone to such type of users. It is prone to such users (or rather bots). When we had the Trac wiki instance running, the amount of spam and corresponding filtering that we did was substantial.
Good point, I had blissfully forgotten about that, and yes you're right, both the issues list and the wiki were under constant spam attack. John.
On Wed, 6 Dec 2023 at 20:24, Vromen, Tomer via Boost <boost@lists.boost.org> wrote:
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.
Not very helpful if the pull request is ignored, e.g. https://github.com/boostorg/intrusive/pull/82.
I feel your point. I'd suggest to request commit access and get the job done yourself, but that only makes sense if someone is willing to remain active for more than just one PR. Best regards, -- Mateusz Loskot, http://mateusz.loskot.net
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@lists.boost.org> 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.
How many libraries is an average user familiar with ? I wouldn't feel confident ranking more than 3 and I have no idea how theses compares to the other boost libraries. Best regards Alain ----- On Dec 4, 2023, at 3:36 PM, Hans Dembinski via Boost boost@lists.boost.org wrote:
On 2. Dec 2023, at 16:57, René Ferdinand Rivera Morell via Boost <boost@lists.boost.org> 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"
I think the results would be very interesting. The top libraries on this list would then serve as examples for everyone else.
We could repeat this poll in regular intervals to reward improvements in documentation.
Best regards, Hans
_______________________________________________ Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Alain O' Miniussi wrote:
How many libraries is an average user familiar with ? I wouldn't feel confident ranking more than 3 and I have no idea how theses compares to the other boost libraries.
If enough users give feedback on their top three / bottom three libraries, the idea is that it will all average out and we'll get a somewhat representative picture. Ranking 150 libraries is obviously untenable and nobody would want to do it.
On Mon, Dec 4, 2023 at 10:00 AM Alain O' Miniussi via Boost < boost@lists.boost.org> wrote:
...
On the new website we can inject a Google-style feedback poll at the top of each documentation HTML page like: "How helpful is this documentation? [ ]/5 stars" Someone has to take lead on writing up a spec and directing the website development team for this. Thanks
On 4. Dec 2023, at 19:03, Vinnie Falco via Boost <boost@lists.boost.org> wrote:
On Mon, Dec 4, 2023 at 10:00 AM Alain O' Miniussi via Boost < boost@lists.boost.org> wrote:
...
On the new website we can inject a Google-style feedback poll at the top of each documentation HTML page like:
"How helpful is this documentation? [ ]/5 stars"
Someone has to take lead on writing up a spec and directing the website development team for this.
Sorry, I was not clear, but yeah, that's what I had in mind. We can realistically only ask users for feedback on the library that they use. It is too much to ask them to compare the documentation of library X to library Y. From the average star rating per library provided by users, we can then publish a ranking of all libraries by the average number of stars per library.
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. 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.
sob., 2 gru 2023 o 17:21 Andrey Semashev via Boost <boost@lists.boost.org> 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.
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.
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. Regards, &rzej;
_______________________________________________ Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
participants (14)
-
Alain O' Miniussi -
Andrey Semashev -
Andrzej Krzemienski -
Hans Dembinski -
John Maddock -
Marshall Clow -
Mateusz Loskot -
Niilo Huovila -
Peter Dimov -
René Ferdinand Rivera Morell -
Robert Ramey -
Ruben Perez -
Vinnie Falco -
Vromen, Tomer