I have had much to say regarding documentation of C++ libraries. see https://www.youtube.com/watch?v=YxmdCxX9dMk&t=2s . I won't repeat here the advice/observations contained in the video. I've also been a persistent nagger and critic of the documentation of C++ libraries submitted to review.
I may be deluding myself (happens a lot!) but I honestly believe that things have improved a significantly. Documentation for libraries recently submitted for review have quite good documentation in my opinion. Ones that occur to me are histogram, out_ptr, mp11, leaf and others. I still have some specific complaints on these, but on the whole I believe that things are much better than they used to be and generally far superior to documentation of other C++ development projects.
I get your complaint about spirit - beautifully prepared documents which reflect a lot of effort. But still seems harder than it should be. Would be interesting to investigate this in light of more recent efforts to determine why this is so.
I appreciate you're bringing this up. Such observations/complaints are very useful. But to make a difference might require investment of some more effort. For example, it would be interesting to look at a few more libraries and list your top/bottom ten. I would guess that the bottom would contain more older libraries. I appreciate that this would be significant effort so I'm not actually asking you to do this.
Robert Ramey
Thank you all for sharing your thoughts about documentation. I admit I've not much experience with other libraries. Good to hear that more recent library docs are considered better. I have sent a private email to Michael Caisse and Joel de Guzman (X3 author) for what I think are improvements for the documentation.
Hans Dembinski I personally find examples very helpful. In some cases, I learned more from reading the unit tests than from the docs, but that is not how it should work. The reference is very important, but there also has to be a user guide that explains some of the concepts and the structure of the library. How it all fits together. We want to empower the user to be creative with the library, not just follow recipes.
I agree with this. For Spirit X3 I do consider the examples in the tutorial too much applications already. While my "toolbox" of parser programming facilities isn't sufficiently filled. With the inviting words from Michael Caisse it seems they are now willing to hear feedback on documentation of Spirit X3. In my first email to them I can only share my perspective that would do it for me. Maybe there are more users and past-users (who have seen value in Spirit but considered it too hard to get along) who can give constructive suggestions about documentation. Also I can share that email of today to see if most people agree with this or just something to provide associations for what they consider harder than necessary. But I don't know if that is appreciated. Best regards, Maarten Verhage