On Thu, Oct 10, 2013 at 4:29 PM, Mathias Gaunard < mathias.gaunard@ens-lyon.org> wrote:

Documentation like this is generated by preprocessing Doxygen XML output to integrate it into Boostbook and have a good look for C++ references. It has most of what you can expect from Doxygen + the Boostbook stuff which gives better cross-referencing than simple Doxygen.

I personally don't understand how one cannot notice that the blue bits that become underlined when you hover them and change colors once visited are hyperlinks (especially since that's also true for any other hyperlink in Boost docs and most of the World Wide Web). What do you suggest would be better?

I believe part of the problem is that everything is blue. For instance, on the boost.lockfree page: http://www.boost.org/doc/libs/1_54_0/doc/html/lockfree/reference.html#header... - The following words are blue: - namespace, template, bool, struct, capacity, template, typename, allocator, class, fixed_sized, queue, spec_queue, stack - Out of those, the following are links: - fixed_sized, capacity, allocator, queue, spec_queue, stack I believe there is a word to describe the concept of building things such that people expect to interact with them. I think it is called an affordance, so a link should "afford" clicking. https://en.wikipedia.org/wiki/Affordance When it is your first time ever on the site, even if you try to hover over one of the blue words, you may choose one that can't be clicked on, then assume the same applies for the others. IMHO, changing the color of links or making the underlines always visible could be helpful. One possible improvement would be what Mario Mulansky described. In the Table of Contents of libraries the Reference section could contain a list of links to headers, classes, functions, metafunctions, and definitions. Then if you click to the reference link where it currently just lists headers it could also provide the synopsis of the aforementioned items and links to the detailed docs. Right now all of the documentation is an extremely deep hierarchical structure, which if I recall my conventions correctly has been moved away from in modern user experience design. Most websites try to focus on getting you to the information you need in as few clicks as possible. That is why I mentioned cppreference.com in my previous email, if you check out that site nearly everything is 3 levels deep or less. Since boost is so much larger a total of 4 levels with the top one being the list of libraries would make sense. Some link to the libs unit test and/or example folders in each library would also be helpful. These are a couple small, concrete steps that would probably help with browsing but aren't too out there. It doesn't help some of the possibilities for improved text which could also benefit, but it does help many things at a high level. As a side note, I wonder if the boost main page could be better served as a wiki of some sort? Cheers! Andrew Hundt