Oliver Kullmann <O.Kullmann@swansea.ac.uk> 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