Re: [boost] Improving Documentation

Subject: Re: [boost] Improving Documentation
From: Andrew Hundt (athundt_at_[hidden])
Date: 2013-10-10 18:07:34

On Thu, Oct 10, 2013 at 4:29 PM, Mathias Gaunard <
mathias.gaunard_at_[hidden]> 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.boost.lockfree.policies_hpp

   - 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