| Re: [cdt-dev] Screenshots in the Reference documentation |
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…
|