[cosmos-dev] Screen captures in the "Help Contents" are evil. Don't use

[Ruth Lee <ruthdaly@xxxxxxxxxx>]

Hi folks,

We touched on this topic briefly in
the Architecture call today. I'm sending out this summary to everyone so
that those who weren't on the call also understand what's expected of them.

First, this is a link to the Eclipse
doc style guide. When writing documentation for eclipse these are the rules
that we are supposed to follow: http://wiki.eclipse.org/Eclipse_Doc_Style_Guide

Note that style guide says that screen
captures are okay as long as you follow the guidelines. I disagree and
think that we should not put in a screen capture unless we have no alternative.
We should avoid screen captures for a few reasons:

• Historically when people are supposed to technically review docs they're supposed to review that the screen captures are still accurate but in my experience people don't do that. The screen captures get out of date in future releases.
• The guideline spells out the OS etc. that screen captures should be in. That forces everyone who wants to capture a screen to use Windows XP, Default colours etc. I suspect that not everyone will have access to a Windows XP machine or that they may be reluctant to change their customizations.
• For every screen capture you add, you still have to describe that screen capture in the "alt" attribute for people who are blind or have vision impairment. You don't save writing time by adding a screen capture. And then you get the fun of testing each image via a screen reader; that is, you listen to a screen reader read out the description of that image. I think that the last time that I ran a screen reader on pages with screen captures it worked out to -- if I took shortcuts -- no less than five minutes per page. If I had done the job thoroughly, which means reading the entire page instead of just the text around the images, then it would have taken weeks. Imagine listening to every page in the "Help Contents" that has a screen capture.
• It's bad for translation. We're not translating COSMOS v1.0 but it's possible that we will in future. Each translator has to recapture the same screen capture in the non-English language. It's a lot of work and some translators will do it and some won't. I don't know why, but it's up to each translation center to make the call on whether they'll do that work or not.

The benefit to you, development, of
not creating screen captures is that it's less work in the long run for
you. 

I propose that if there is a need to
add a screen capture then it should be reviewed by Rich Vasconi first for
approval.

--Ruth.

Ruth Lee
IBM Toronto Lab
ruthdaly@xxxxxxxxxx
T/L 313-4453