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

Subject: Re: [Boost-users] Boost.Beast vs Boost.Asio
From: Gavin Lambert (boost_at_[hidden])
Date: 2018-12-04 22:32:10

On 5/12/2018 03:20, Robert Ramey wrote:
> 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.

+1

Authors must write the first version of the docs, because they're the 
only ones who know the library well enough to do so.

They should remain responsible for the "official" docs thereafter, but 
incorporate constructive feedback from others on review and trying to 
actually use them.  Things are usually less obvious than the author 
assumes. :)

And design and layout of the documentation is just as important (if not 
more important) than the design of the code itself.  No matter how 
finely-crafted the code is, a library is useless if nobody knows how to 
actually use it, or their first instinct is to use it "wrong".