Very well said ! On Mon, Dec 12, 2011 at 2:26 PM, Beman Dawes <bdawes@acm.org> wrote:
Looking at
http://boost-sandbox.sourceforge.net/libs/multiprecision/doc/html/multipreci...
http://boost-sandbox.sourceforge.net/libs/multiprecision/doc/html/multipreci... 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
_______________________________________________ Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost