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 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, Dec 2, 2023 at 1:12 PM Mateusz Loskot via Boost wrote:

On Sat, 2 Dec 2023 at 16:58, René Ferdinand Rivera Morell via Boost wrote:

...

On Sat, Dec 2, 2023 at 2:08 AM 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.

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 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-guide....

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, 2 Dec 2023 at 21:26, René Ferdinand Rivera Morell wrote:

On Sat, Dec 2, 2023 at 1:12 PM Mateusz Loskot via Boost wrote:

...

On Sat, 2 Dec 2023 at 16:58, René Ferdinand Rivera Morell via Boost wrote:

...

On Sat, Dec 2, 2023 at 2:08 AM 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.

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 Mon, Dec 4, 2023 at 8:36 AM Hans Dembinski 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"

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

Can we organise a user poll that ranks all Boost libraries on how well documented they are?

Sounds fun, how do we implement this?

On Mon, 4 Dec 2023 at 21:05, 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 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

...

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 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 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 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 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.

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 4. Dec 2023, at 19:03, Vinnie Falco via Boost 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.

sob., 2 gru 2023 o 17:21 Andrey Semashev via Boost 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