Best boost documentation
Hi, I’m preparing a library to be proposed and I’m adapting the documentation I had to be more Boost-like. I saw there is different writing styles in the documentation. Something I’m specially interested is in the document structure, I saw some start with a tutorial, others with an overview of the concepts, others just go straight to the internals. I’m wondering if there is a preferred style or document structure to use. Best regards, Damian
-----Original Message----- From: Boost [mailto:boost-bounces@lists.boost.org] On Behalf Of Damian Vicino Sent: 23 January 2015 08:48 To: boost@lists.boost.org Subject: [boost] Best boost documentation
Hi, I’m preparing a library to be proposed and I’m adapting the documentation I had to be more Boost-like.
I saw there is different writing styles in the documentation. Something I’m specially interested is in the document structure, I saw some start with a tutorial, others with an overview of the concepts, others just go straight to the internals.
I’m wondering if there is a preferred style or document structure to use.
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. Providing links to external documents, other Boost libraries and to internal details is important to the user. The best tool, again in my opinion, is the Quickbook, Doxygen and Autoindex toolchain. You will find a number of more recent libraries use this. It provides a Boost-ish 'look'n'feel. If you would like help to prototype your proposed library documentation, contact me off list. Paul --- Paul A. Bristow Prizet Farmhouse Kendal UK LA8 8AB +44 (0) 1539 561830
On January 23, 2015 5:05:55 AM EST, "Paul A. Bristow"
-----Original Message----- From: Boost [mailto:boost-bounces@lists.boost.org] 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 use.
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. ___ Rob (Sent from my portable computation engine)
participants (3)
-
Damian Vicino -
Paul A. Bristow -
Rob Stewart