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

From: Reid Sweatman (drunkardswalk_at_[hidden])
Date: 2004-09-29 22:21:06

> -----Original Message-----
> From: boost-bounces_at_[hidden] 
> [mailto:boost-bounces_at_[hidden]] On Behalf Of David Abrahams
> Sent: Wednesday, September 29, 2004 4:59 PM
> To: boost_at_[hidden]
> Subject: [boost] Re: [Poll] New look-n-feel for Boost documentation

<snipped>

Most of the meat of my comments is at the bottom, not inlined, so please
look there before dismissing this as a minor crank post.  <g>

> Y'know, I like blue too, but it shouldn't be used for 
> non-links. Section headings should be black, just like the 
> rest of the non-linked text.  Black on white reads much more 
> easily (yes, according to
> research) and that applies to headers as well as body text.

Yes, but pure white backgrounds pixellate something fierce; whether it bugs
you or not depends on your neurophysical makeup.  I can't stand it,
personally, and often modify pages I capture to be just a little off in some
desaturated direction.  Other research shows that the one color both sexes
uniformly like is teal, so it's no surprise that my backdrops are very pale,
desaturated teal, leaning in the blue direction.  For brief periods I can
live with white; long reading, though....  How about a background color like
RGB: 213, 244, 244?  That's barely noticeable to most people, but goes a
long way towards reducing pixellation and eye-strain.  Doesn't interfere
with any of the current color choices for text, either.
 
> > I also like the idea of collecting all the documentation into one 
> > large hyperdocument.  It makes Boost look more like a serious 
> > collection of libraries rather than a hodgepodge thrown together. 
> > Making all the docs look consistent goes a long way towards 
> that.  I 
> > also agree with Thorsten that it would be nice to get an automagic 
> > syntax highlighter in the toolchain that preprocessed code 
> blocks to 
> > produce some nice color-highlighted html.  It would be 
> really nice if 
> > it emitted code on a fairly fine-grained scale (lots of syntactic
> > elements) so that there is plenty of flexibility for writing custom 
> > css configs for your favorite syntax-highlighting setup (that way, 
> > ambitious people could view the code in the docs in the same scheme 
> > that, say, their IDE uses).  Of course, I have no idea how 
> much work 
> > that would be, and I'm not exactly in a position to 
> volunteer the time 
> > right now, but it seems to me that Wave must already have 
> some of the 
> > capability, given that it knows enough C++ to do preprocessing.
> 
> You have to be careful about that.  We could easily make 
> things worse for many people by making the wrong color 
> choices.  In that case, black would be better.

I agree with most of the comments here, and would also prefer black text, no
matter what the background.  On the HTML pages, I'd personally prefer font
choices that are just a bit thicker-looking, maybe one font size larger
(it's hell going from 20/10 vision to what I have now), but I realize that
that's a personal preference, and wouldn't do more than note that some of
the text is particularly small and hard-to-see at even 1280x1024 resolution.

The issue I would raise, though, is accessibility.  I'm not personally
affected by this, but my wife's position forces her to deal with it at all
times, so I'm always aware of such issues.  In particular, the use of frames
in the sample links could be a problem, and I suspect that no one's given
accessibility much thought.  Certainly it makes web sites much harder to
maintain, and leads to web code that's anything but elegant.  Still, I'll
toss out the following links, and apologies to anyone (possibly *everyone*)
here who's already thoroughly familiar with it.  First, there's the W3C/WAI,

    http://www.w3.org/TR/WCAG10/#gl-own-interface 

Note specifically Para. 2.2.  Then there are the Federal standards:

    Section 508 Standard §1194.21
    http://www.section508.gov/index.cfm?FuseAction=Content&ID=12

The problem with frames specifically, nice though they can be, is that they
prevent a number of operations necessary for software for the disabled to
function.  As just one example, they prevent bookmarking.  They also can
interfere with a number of other mandated items, but the list would be too
long to bother with here.  If this is regarded as an issue, I'd merely
suggest reading through the appropriate documents.  Boost may not be under
the restrictions imposed on government sites (yet), but it seems to me that
if the goal is to get as much Boost code into the next official spec as
possible, it could become an issue, as the governing bodies (I know,
preaching to the Chorister and Organist, let alone the choir <g>) definitely
have government relationships.

Incidentally, the laws in the UK are completely different, and more
restrictive than those here.  I don't have a link at hand for UK
requirements, but the most simple web search will turn up hits by the score.