Boost logo

Boost Users :

Subject: Re: [Boost-users] Boost.Beast vs Boost.Asio
From: Robert Ramey (ramey_at_[hidden])
Date: 2018-12-04 14:20:40

On 12/4/18 2:17 AM, Paul A. Bristow via Boost-users wrote:

> Authors should never write their own docs ;-)

I'm aware that this suggestion is made in jest. But I think it reflects
the view of many authors that documentation is a chore that can
separated from the library development and design which can most
expediently left for last, delegated to doxygen or just skipped
entirely. I think this view totally wrong. It's a sure sign that the
one's library is messed up when documenting how to use it and how it
works is too difficult to do. If one is crafting the documents and the
code together, difficulties in keeping the documentation working can
motivate improvements in the design which make things much simpler.
We've had boost submissions where the document is a mess - and generally
that implies that the code is also.

> Both libraries could (should even) helpfully cross-link each other?

I think that would be mistake you'd regret for the rest of your life.
Cross-linking (in both directions) would effectively make beast/asio one
giant library. I know you're talking about only the docs. But if you
feel you need to do it for the docs, you've likely intertwined the
concepts which determine the design and scope of each library. Bad idea.

> A PR that is just a link is much more likely to be accepted than something that needs real effort?
> Paul
> ---
> Paul A. Bristow
> Prizet Farmhouse
> Kendal UK LA8 8AB
> +44 (0) 1539 561830

Boost-users list run by williamkempf at, kalb at, bjorn.karlsson at, gregod at, wekempf at