Subject: Re: [boost] Best boost documentation
From: Rob Stewart (rob.stewart_at_[hidden])
Date: 2015-01-23 10:02:31
On January 23, 2015 5:05:55 AM EST, "Paul A. Bristow" <pbristow_at_[hidden]> wrote:
> > -----Original Message-----
> > From: Boost [mailto:boost-bounces_at_[hidden]] On Behalf Of
> Damian Vicino
> > Hi,
> > Iâm preparing a library to be proposed and Iâm adapting the
> documentation I had to
> > be more Boost-like.
> > Iâm wondering if there is a preferred style or document structure to
> There are no fixed rules, but I think that a tutorial-ish "Why use
> this library? What it does for you."
> is the best way to start.
Those questions aren't address by a tutorial add I understand the idea. They are addressed by an Introduction or Motivation section.
A tutorial walks through how to use the library, step by step with discussion.
> Providing links to external documents, other Boost libraries and to
> internal details is important to the user.
"Internal details?" I'd want to know about the API, the exceptions emitted, etc., and I'd want to know about performance characteristics, for example, but not internal details.
> The best tool, again in my opinion, is the Quickbook, Doxygen and
> Autoindex toolchain.
Right, at least when the author doesn't have contrary ideas about structure and layout.
(Sent from my portable computation engine)
Boost list run by bdawes at acm.org, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk