[boost] Re: Customer Friendlier Boost Installation

From: David Abrahams (dave_at_[hidden])
Date: 2005-05-25 18:16:10

Oliver Kullmann <O.Kullmann_at_[hidden]> writes:

> But for these "millions of C++ users" Boost is not the right
> choice. 

It should be.

> The exciting thing about Boost is that it is Avantgarde, a
> good deal of interesting research(!), and not compromising on
> quality. That's at least my understanding of Boost.

We don't want to be Avantgarde/research; to the extent that we are, we
need to fix it.

> Sure, it would be nice to have this additional layer for beginners,
> but that simply seems not to be feasible.

It is certainly feasible.  We just need to know what to do, and
allocate the resources to do it.

> Here comes one proposal: If it would be easier for boost members to
> edit existing documentation, then at least I could contribute quite
> a bit. But I mean "really easy", for example a wiki with the current
> documentation, where one can just goes and change it (and there is
> somebody responsible for each (sub-)library); this could really
> improve documentation a lot.

Or it could result in the documentation getting a lot worse.  I
certainly have seen incorrect advice posted often enough about
Boost.Python that I don't want even some experienced Boost.Python
users to change the official documentation without getting a chance to
review the changes first.

> (One should have as a general guideline, that additions are
> conservative, that is, they only extend and correct the given text,
> but they do not eliminate something (because one doesn't like the
> style etc.). And my focus here is really on the *text*, which quite
> often assumes some common ground, which more often than not is not
> given.)

Even adding information to existing text can make it worse.  But
anyone motivated to make significant contributions to the
documentation can probably get CVS write access, which is IMO easier
to use than a Wiki for any substantial writing where you have to edit
in a browser window or copy/past back and forth.

> Here one example (about documentation in general): I know of one MSc
> project of a colleague, based on Spirit, which nearly failed because
> the student didn't have the right understanding what Spirit really
> was supposed to do (that "recursive decent parser thing"), and also
> I fall into the same trap (but it only cost me a few hours). So an
> easy thing would be to go to the *current* Spirit documentation, and
> add at one or two places a few warnings. This could help a lot. But
> first writing an e-mail, explaining all this, etc. costs too much
> time. Just adding these sentences on a wiki, that should be it, and
> the maintainer then is automatically alerted.

Well, that's an interesting idea.  But it would take a *lot* of work
to set up.  Do you think enough people would be motivated to edit the
documentation that it would be worth the effort?  As you say, "it's
not so easy to get the documentation written," which is in part
because people don't like writing docs.

Hmm, a QuickBook documentation Wiki... it has a certain ring to it.

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