"Andy Little" <andy@servocomm.freeserve.co.uk> writes:
"David Abrahams"
David Greene <greened@obbligato.org> writes:
E. Is the documentation good enough for a boost library?
This has been made very clear and Andy has graciously accepted the suggested documentation changes.
Andy has indeed graciously accepted criticism of the documentation, for which I commend him.
Your criticism mainly concerned the C++ Concepts section of the documentation for PQS. What might help is some examples of what you consider good C++ Concept documentation.
The C++ standard does a pretty decent job. There's also the SGI STL website. There's also the Boost Graph library. The "new iterator concepts" document in the iterator library docs does pretty well. And you can always start at http://www.boost.org/more/generic_programming.html#concept.
What's missing for me is a clear intention to actively pursue better docs himself, as opposed to being willing to accept specific edits that other people happen to suggest. If we leave the quality of our documentation (or code, for that matter) up to people who rewrite it for us, we won't have much quality at all.
I havent asked and don't expect anyone else to write the PQS documentation for me FWIW.
I didn't think you had, but I was trying to make it clear in general that graciously accepting criticism isn't enough.
I have stated that a truly generic quantities library ( encompassing all unit systems) is beyond my skill and knowledge and that someone else would need to write that if that is the requirement for a Boost Quantities library.
Let me be very clear: my complaint was not with the level of generality of the library, if that's what you mean by "truly generic;" it was with the quality of the specification.
I would be happy to do what I could to help in the SI area though, in that case.
IMO the library author has to be willing to take responsibility for making the docs work; any help from the outside is a bonus.
I agree with that !
FWIW Here are some rough notes to self regarding the PQS documentation
*Non C++ concepts (definition of terms).* Remove C++ specific and especially PQS library implementation details from here. Move this section to the back of the docs.
*C++ Concepts* Some entities are metafunctions hiding as Concepts. Look at other C++ concept documentation and see how it works. Link to headers.
Good. Let me stress again that you shouldn't underestimate the value of writing concept checking classes and archetypes for your library (see Boost.ConceptCheck). Those will lead almost directly to coherent concept documentation.
*Writing Tools.*
Frankly I have had some problems with QuickBook. This is partly because I used an early version - Problems with links, layout, features, formatting, some bugs, Partly because it provides an alien layout. Partly Issues with not being able to integrate a map when required and not being able to integrate html, Javascript etc. Maybe newer Quickbook is better.Maybe try a different html generator. Maybe go back to raw html.
OTOH maybe a bad workman blames his tools ...
*Getting started section.* Basically seems to be acceptable. Try to improve the examples and pick up on comments made during the review. Consistent examples, copy paste to code, show output, link to actual code etc.
*Informal semantics of Operations section* I am repeating myself 3 times showing the functionality of the t1_quantites operations, first in Getting Started section, second in Informal Semantics section, finally in The C++ concepts section. This actually works well for users concentrating on the Getting started section because its light, but I wonder if I can somehow combine the informal semantics with the C++ Concepts without getting very tedious indeed.
*Synopsis* Unfinished. Maybe move this forward so users can see it after getting started section.
*Overall Layout.* Docs are very incomplete Many sections missing. Lose pdf compatibility. Try moving away from serial layout back to preferred star/hierarchical layout. as always use diagrams, not text where possible (especially when adding Geometry etc). Add some larger more ambitious examples. Link to the code examples. Show more hints and tricks (such as Typeof when available). Show alternative useages/views( ie 'Jesper Schmidts'/'SIunits' style) than the Simple Interface shown in Getting Started section. Mechanisms for switching quantities /floats for checking without loss in performance etc.
Thats it so far and it may all change of course. I must spend another good few sessions rereading all the reviews and comments too.
regards Andy Little
_______________________________________________ Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
-- Dave Abrahams Boost Consulting www.boost-consulting.com