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

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

Darren Cook <darren_at_[hidden]> writes:

>>>>   E. Is the documentation good enough for a boost library?
>>>...
>> ... 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.  IMO the library author
>> has to be willing to take responsibility for making the docs work; any
>> help from the outside is a bonus.
>
> It may be worth distinguishing between reference docs and tutorial docs.
>
> I agree that the library authors have to be responsible for the former
> (which judging by the subject of this thread is what we are talking about).
>
> But many times the tutorial documentation is better written by someone
> else, someone who can see the wood not the trees.

Maybe, but the library author has to be responsible for both.  Who
does the actual writing of either one is not my concern.

> Incidentally when I'm in the early stages of evaluating a library
> the existence of more than one "how-to" article, and articles
> written by project outsiders, are more important than just about
> anything else.  Reference docs are useful but less important as I
> can always look at the source if I really need to understand
> something.

That's fine for you if you're comfortable with it, but it won't tell
you anything about how to use the library correctly.  It will just
tell you how to do something that works with this particular version
of this particular implementation.  "Use the source, Luke" is not one
of those open-source sayings we have traditionally encouraged around
Boost.  For Boost, coherent specification is at _least_ as important
as working implementations.

-- 
Dave Abrahams
Boost Consulting
www.boost-consulting.com