Thanks everyone for the replies – they have been quite helpful.
The consensus I hear is as follows:
· to remove the screenshots from the individual Menu documentation pages (in line with the JDT documentation),
· but to still have screenshots in (most of) the Preference Pane documentation pages (because a dialog box is more complex than the linear (if maybe nested) list of items in a menu).
· A general preference for screenshots in documenting toolbars (which I greatly agree with)
· A strong preference for screenshots in procedural help, like the Getting Started guides.
I’ll open various bugzilla entries to work on this as I have available time.
Jesse
From: cdt-dev-bounces@xxxxxxxxxxx [mailto:cdt-dev-bounces@xxxxxxxxxxx] On Behalf Of kesselhaus
Sent: Tuesday, March 26, 2013 1:27 PM
To: cdt-dev@xxxxxxxxxxx
Subject: Re: [cdt-dev] Screenshots in the Reference documentation
Hi,
From my point as a user, I very much like some screenshots, though, they should be selected wisely and be not outdated.
It gives you an overview .. a picture of what a program looks like and where to find it.
You can more easily find out, if you are in the right position, or just on the wrong end of dialogs and options.
Last year, I was training our new software developers in a new location. I made lots of presentations about
how to use our tools including Eclipse/CDT and e.g. Rhapsody, DOORS and other tools.
Preparing a 2h powerpoint slide took me about 1..2 days and most of the time was taking and preparing screenshots
and bringing it into a form to show procedures.
I myself also dislike pure textual guides, sometimes I just get lost in such guides.
Just think about, if you tell someone to go to "Window"->"Preferences"-->"C/C++"->"Editor"->"Syntax Coloring" ...
You hit here several things at once .. MenuBar, MenuItem, TreeItem, TreeItem subNodes, Prefrence Settings page
which also has sub trees until you finally hit the settings for a specific Color/Font setting.
There are also several Toolbars, like the main toolbar, a toolbar in a view (e.g. debugger, outline, search,
object/type hierarchy, include browsers etc. .. I think, if you just describe that textual, users might get lost.
Am 22.03.2013 01:55, schrieb Marc Khouzam:
I think it may be good to look at each case individually. If the textual description is short and easy to understand, then I think it is fine to get rid of the screenshot.
"A picture is worth a thousand words"; if a screenshot is meant to illustrate something that can be described clearly in one sentence, then we probably don't need the screen shot. It'll be a judgment call on your part.
BTW, thank you for improving the docs. It was seriously needed and will be very valuable to users.
Best regards,
Marc
----- 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…
_______________________________________________
cdt-dev mailing list
cdt-dev@xxxxxxxxxxx
https://dev.eclipse.org/mailman/listinfo/cdt-dev
