Re: [Boost-users] Boost.Beast vs Boost.Asio

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
> [phone]
>