[boost] [multiprecision] Docs missing the basics

Subject: [boost] [multiprecision] Docs missing the basics
From: Beman Dawes (bdawes_at_[hidden])
Date: 2011-12-12 08:26:15

Looking at
http://boost-sandbox.sourceforge.net/libs/multiprecision/doc/html/multiprecision/intro.html
http://boost-sandbox.sourceforge.net/libs/multiprecision/doc/html/multiprecision/intro/about.html
I see a lot of details and commentary, but nothing about the big picture.

* Needs an explanation of what "multiple precision" means. I would
expect the first sentence to be something like "The multiprecision
library, like other multiple precision libraries, provides arithmetic
types that are not limited to the precision of the built-in C++
arithmetic types."

* Needs an early explanation of what kinds of arithmetic types are
supported. I would expect the second sentence to be something like
"Integer, floating, and user defined types are supported." (I can't
even tell from the current intro whether integers and UDTs are
supported!)

* Needs an early "Hello World" level example. The third sentence might
begin a new paragraph, something like "Here is a simple example of
muliprecision use: ..."  Please remember that the point of a "Hello
World" example is to introduce the simplest possible use of the
library, not to demonstrate its power!

* Although, not as critical as the previous issues, a bullet list of
key features would be easier to read than plowing through a bunch of
dense text.

Once you've done that, the reader can make a quick blink decision as
to whether to read on. A reader who isn't interested with thank you
for not wasting their time plowing through a lot of text only to
discover the library isn't of interest to them.

Once docs provided the above view from 30,000 feet, then the remaining
introductory details you've provided become interesting and the reader
has enough orientation to absorb them.

Good luck with this library!

--Beman