Re: [boost] [Poll] New look-n-feel for Boost documentation

From: Rob Stewart (stewart_at_[hidden])
Date: 2004-09-30 08:51:47

From: "Eric Niebler" <eric_at_[hidden]>
> 
> Joel de Guzman and I, with the help of many smart folks on the 
> boost-docs list[*], have been working on improving the look-n-feel of 
> Boost's documentation. We're ready to commit the new style, but wanted 
> to check here first.

Thanks to all those involved.  Generally, the new style is clean,
professional, and attractive.  I do have a few complaints,
however.

1. My browser's "always underline links" setting is not being
   respected.  I prefer links to be underlined so they are more
   visible.  Color alone is not an indication.  In case it
   matters, by user agent string is:

   Mozilla/5.0 (X11; U; SunOS sun4u; en-US; rv:1.0.1) Gecko/20020920 Netscape/7.0

2. My browser's link colors are not being honored.  Thus, the
   link color isn't my normal link color and they don't change to
   indicate when I've visited them.

3. Sans serif text is harder to read.  You should use a font with
   serifs for the body text and sans serif fonts for headings.

4. Some things don't adapt well to differing resolutions and font
   sizes.  Consider the preferred/portable syntax table at
   http://zigzag.lvk.cs.msu.su/~ghost/boost_docs/function.tutorial.html#id478061.
   At my default settings, I see half of the second column.  Were
   the table not offset so far, I'd see the whole thing.
   However, it is clear that things are set to not wrap
   (non-breaking spaces, perhaps?), so the side-by-side
   presentation means the table is likely to be wide and trigger
   scrolling.  The second preferred/portable syntax entry in that
   section recognizes the problem and uses two tables, one above
   the other.  Were it not for the extra large offset, the
   "Preferred syntax" table would fit at my default settings.
   The point is that while you cannot control a reader's
   resolution or font choices, and scrolling is inevitable,
   reducing the offset and avoiding wide, non-wrapping layouts is
   superior.

5. In
   http://zigzag.lvk.cs.msu.su/~ghost/boost_docs/function.tutorial.html#id478410,
   a list is introduced with, "Three such libraries are
   summarized below:," but there are no bullets setting off the
   three paragraphs.  Is this a Boost.Function documentation
   issue or is this a consequence of the new style?  If the
   latter, there should be bullets to clearly delineate each
   item.

6. At the bottom of that same page, links to boost::ref refer to
   here:
   http://zigzag.lvk.cs.msu.su/~ghost/boost_docs/reference_wrapper.html#id444666,
   which says nothing about "boost::ref."  References to that
   name appear earlier in the linked document.  Again, I don't
   know whether this is an issue with the Boost.Function
   documentation or the new style, but it will be a source of
   confusion.

7. The links to the documentation should probably be encoded by
   the author similarly to those in the C++ Standard.  That is,
   instead of id444666, the link name could be "ref.desc.ctor" or
   something.

8. When looking at
   http://zigzag.lvk.cs.msu.su/~ghost/boost_docs/ref.reference.html#header.boost.ref.hpp,
   there's no indication that there is documentation on
   boost::reference_wrapper.  The link mentioned in 6 got me to
   the documentation page, but when I went up to
   http://zigzag.lvk.cs.msu.su/~ghost/boost_docs/ref..html, and
   then to
   http://zigzag.lvk.cs.msu.su/~ghost/boost_docs/ref.reference.html,
   I was unsure how to get back to
   http://zigzag.lvk.cs.msu.su/~ghost/boost_docs/ref.reference.html#header.boost.ref.hpp,
   since the link was in the "Header" section.  Is this a
   consequence of the documentation or the new style?  I'd prefer
   to see something like this in the "Reference" section or a
   "Description" section:

      reference_wrapper - <brief>
      ref - <brief>
      cref - <brief>
      is_reference_wrapper - <brief>
      unwrap_reference - <brief>

   where the names are the same links as in the Header section.

9. Headings and links should not share the same color, whatever
   choice you make for them.  Blue is the traditional link color,
   but, as I said above, I don't like my colors being overridden.

10. I don't like "pure" white backgrounds.  The teal suggestion
    made earlier would be good.  An off-white would be fine, too.

-- 
Rob Stewart                           stewart_at_[hidden]
Software Engineer                     http://www.sig.com
Susquehanna International Group, LLP  using std::disclaimer;