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

From: David Abrahams (dave_at_[hidden])
Date: 2006-06-13 23:37:20

"Andy Little" <andy_at_[hidden]> writes:

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

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