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