Re: [boost] [multiprecision] Docs missing the basics

Subject: Re: [boost] [multiprecision] Docs missing the basics
From: Zoltán Tóth (zo1980_at_[hidden])
Date: 2011-12-14 15:56:57

Very well said !

On Mon, Dec 12, 2011 at 2:26 PM, Beman Dawes <bdawes_at_[hidden]> wrote:

> 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
>
> _______________________________________________
> Unsubscribe & other changes:
> http://lists.boost.org/mailman/listinfo.cgi/boost
>