[
Date Prev][
Date Next][
Thread Prev][
Thread Next][
Date Index][
Thread Index]
[
List Home]
|
Re: [cdt-dev] Screenshots in the Reference documentation
|
Jesse
I think screenshots can be useful in reference documentation where they
serve to reduce lengthy descriptive text. On the other hand, in my
experience screenshots tend to require updating more frequently than the
associated text. If some screenshots can be eliminated this may reduce
the effort involved in ongoing maintenance.
To be clear, I am very much in favour of screenshots when describing
step-by-step procedures such as in a getting started guide.
Depending on how CDT HTML documentation is generated, it may be possible
to instruct the browser to scale large images to fit the current page
width and add a "Click to view full size" anchor to each image.
John Dallaway
----- Original Message -----
From: Jesse Weinstein <jesse.weinstein@xxxxxxxxxxxxx>
To: "cdt-dev@xxxxxxxxxxx" <cdt-dev@xxxxxxxxxxx>
Sent: 21-03-2013 19:48
Subject: [cdt-dev] Screenshots in the Reference documentation
Currently we have (mostly very out-dated) screenshots at the top of most
of the menu, preference and other reference documentation pages (e.g. in
the org.eclipse.cdt.doc.user plugin). I'm not actually convinced that
the screenshots are actually a Good Idea. They require the help pages to
be very wide, which prevents their use in context (i.e. when you click
on the (?) in the preferences, they require regular updating, and they
are not consistent across platforms. And basically, they're redundant
with the actual menus or preference panes.
Looking at the other manuals, it's a mixed bag. JDT doesn't have
screenshots; the Platform has them, but they aren't at the top; PDE has
them for preferences, but not for menus (although that might just be
because it doesn't have much menu documentation); EGit has lots (in a
somewhat confusing arrangement); the JavaScript Development Guide has
them (with a vast amount of whitespace). So I suppose they are overall
more used than not, but I'm still not convinced they actually add anything.
I'd love to hear folks thoughts and opinions on the topicÂ…
