Re: [boost] Improving Documentation

Subject: Re: [boost] Improving Documentation
From: Andrew Hundt (athundt_at_[hidden])
Date: 2013-10-11 12:45:38

On Friday, October 11, 2013, Mathias Gaunard wrote:

> On 11/10/13 00:07, Andrew Hundt wrote:
>
> 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<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
>>
>
> It's clearly not the same shade of blue though. The links (capacity,
> allocator, fixed, queue, spec_queue, stack) are closer to a greenish blue.
> Do they appear difficult to distinguish to you?
>
> Maybe the color palette could be changed.

It isn't just me. I believe two others in this email chain mentioned it
took them a while to figure out too, and I have had to explain it to other
users who are not on this list. The shades certainly don't "pop" and it
could just be more syntax highlighting. There isn't anything distinguishing
it a a link when you just look at the page and imagine not already being
familiar with this documentation layout. Doxygen and other documentation
tools don't really have anything like it.

>
> Some link to the libs unit test and/or example folders in each library
>> would also be helpful.
>>
>
> I agree for examples, but I don't think unit tests should appear in the
> documentation.
>
> They can be obscure test cases that users don't need to worry about.
>

Yeah, it would be great if everything had micro examples at the bottom of
each page but often the only thing that exists is a unit test. While it
isn't a great situation it would be better than nothing.

Cheers!
Andrew Hundt