Re: [boost] Improving Documentation
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
-----Original Message----- From: Boost [mailto:boost-bounces@lists.boost.org] On Behalf Of Andrew Hundt Sent: Friday, October 11, 2013 5:46 PM To: boost@lists.boost.org Subject: Re: [boost] Improving Documentation
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.loc kfree.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.
Ok - if you have some concrete proposals, please experiment with your \boost-root\doc\srcboosbook.css the colors are defined in this section /* Links */ a, a .keyword, a .identifier, a .special, a .preprocessor a .char, a .comment, a .string, a .number { color: #005a9c; } a:visited, a:visited .keyword, a:visited .identifier, a:visited .special, a:visited .preprocessor a:visited .char, a:visited .comment, a:visited .string, a:visited .number { color: #9c5a9c; } h1 a, h2 a, h3 a, h4 a, h5 a, h6 a, h1 a:hover, h2 a:hover, h3 a:hover, h4 a:hover, h5 a:hover, h6 a:hover, h1 a:visited, h2 a:visited, h3 a:visited, h4 a:visited, h5 a:visited, h6 a:visited { text-decoration: none; /* no underline */ color: #000000; } There are some useful links to colors in this recent post about coloring text in Quickbook. https://svn.boost.org/trac/boost/ticket/5860#comment:11 You could post 'Andrew's Favorite Colors' for user comment?
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.
IMO, library docs are not complete without at least one working example, including code snippets in the main text and link to the actual code so users can read and download easily. Cheers Paul
participants (2)
-
Andrew Hundt -
Paul A. Bristow