Re: [boost] [Review][PQS] Concept names?

From: Andy Little (andy_at_[hidden])
Date: 2006-06-12 14:54:46

"David Abrahams"
> David Greene <greened_at_[hidden]> 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.

> 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 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. 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.

*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