Oodini wrote:
Hello,
I am an user, and I am currently reviewing all the Boost libraries.
I am a user also.
But for a common user, some needs are not satisfied in the libraries descriptions.
This is an understatement.
The Boost organization should compel the libraries authors to put in their documentation :
1. the history of all releases, with notes for each release 2. the motivation of their library 3. when they offer services similar to the ones provided by the STL, why did they feel the need to complete it, and what are the differences
many library documents have a section called "rationale" for this
3. for the relevant libraries, their status regarding the new features of C++11 (are they obsolete ? do they remain some differences ? ex : Array, Chrono, DateTime), especially the ones related to TR1
This is a problem. What happens with a library from 10 years ago? Is being a library developer a life sentence? I understand the problem but I don't see definitive solution. The only way we "compel" authors to put things in a documentation is through the review/approval process. It's better than nothing but has not been enough to improve documentation.
An homogeneous structure for the documentation would be welcome.
I understand the motivation - but again - lot's of problems in practice. Here is my take on the above. a) In general, C++ Library Documentation is generally very poor and hard to understand. It suffers from all the above mentioned problems. Boost library documentation is better than most - but still very uneven quality between libraries. b) Although many believe that there is some sort of "formal" standard for reference documentation there is not. There is a wide variation among developers on what should be in documentation and what should not be. Suggestions for documentation formats and content vary widely. The boost page on this subject is very hard to find. c) The requirements for documentation varies amongst the different types of things being documentated: types, functions, classes, concepts templates, etc. d) The fact that is extremely easy to identify poor documentation in no way makes it easier to write good documentation. e) more pages of documentation doesn't necessariliy mean that the the documentation is better. One thing I would suggest for the real user is to buy a few books: a) A good C++ reference - I use The C++ programming language - Stroustrup b) All the books by Scott Meyers b) If you're going to use templates - C++ Templates - Vandevoorde & Josuttis c) If you're going to even look at mpl - C++ Template Metaprogramming - Abrahams & Gurtovoy d) If you're going to use STL -STL tutorial and reference - Musser & Saini e) If you're going to use Boost - The Boost C++ Libraries (or similar book) - Boris Schäling I realize that this sounds like a really dumb suggestion. There are two facts which jump out at me: a) I probably consult at least one of these books every single day. b) as a contract developer, I work at various companies. 1) I have never seen more than one of these books at any customer site. 2) I have had to purchase any C++ book out of my own funds. So, there is much, much more to this problem than your question would suggest. You will all be hearing much, much more from me on this topic in the near future. Robert Ramey