From: Hans Dembinski (hans.dembinski_at_[hidden])
Date: 2020-05-04 09:24:19
> On 4. May 2020, at 10:29, Andrzej Krzemienski via Boost <boost_at_[hidden]> wrote:
> These are the guidelines that I learned from Robert Ramey's talk on
> documenting a library (https://www.youtube.com/watch?v=ACeNgqBKL7E). As a
> potential user I need to learn in no more than 5 minutes: what the library
> does, how I will use it (LEAF documentation does it perfectly), and what
> are the requirements. For the last point I would expect to see: "your
> platform needs to support TLS, and your program cannot use coroutines in
> asynchronous manner." IOW: high-level design trade-offs should be
> documented up front.
On that note, we have a documentation guideline which says exactly that:
"General introduction to the library. The introduction particularly needs to include: A very high-level overview of what the library is good for, and perhaps what it isn't good for, understandable even by those with no prior knowledge of the problem domain."
Boost list run by bdawes at acm.org, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk