[multiprecision] Docs missing the basics
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
On Mon, Dec 12, 2011 at 8:26 AM, 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.
[snip]
Good luck with this library!
I agree with everything Beman said, and have only one small point to add: be sure to tell the reader early on which headers to #include for what and what namespace things are in. This information is not always easy to find (even in other Boost docs) and I've often found myself looking in the header files themselves to find out either what the minimal set of headers are for a piece of functionality. A good place for this information might be .../intro/architecture.html if there is a lot to talk about. I really hope this library is accepted! Greg
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
These docs are not intended for public consumption yet! As should be blinding obvious :-) They are only on boost-sourceforge because SVN is unsuitable for repeated upload of all the many files that Doxygen generates (with different filenames each time) and this is a convenient way in which the authors can view the same resulting html. (And when it is suitable for public view, it will take some load off the hard-pressed SVN server). Please ignore until there is a proper announcement. Paul PS Both Christopher Kormanyos' multiprecision library and the orthogonal expression template-enabled John Maddock version building on it are under active development, but are both big projects, so 'don't hold your breath', but 'watch this space' ;-) --- Paul A. Bristow, Prizet Farmhouse, Kendal LA8 8AB UK +44 1539 561830 07714330204 pbristow@hetp.u-net.com
-----Original Message----- From: boost-bounces@lists.boost.org [mailto:boost-bounces@lists.boost.org] On Behalf Of Zoltán Tóth Sent: Wednesday, December 14, 2011 8:57 PM To: boost@lists.boost.org Subject: Re: [boost] [multiprecision] Docs missing the basics
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/mult iprecision/intro.html
<snipped>
participants (4)
-
Beman Dawes -
Greg Rubino -
Paul A. Bristow -
Zoltán Tóth