Boost logo

Boost Users :

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.


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

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