Comments & Updates

Titlebar icons

Question regarding 1.5.5.3.2 "Titlebar icons": Why are we documenting the behavior of a widget on a specific platform with specific theme enabled? These values are not guaranteed even just looking at windows alone. (Randy Hudson)

Messages

Somewhere around guideline 1.8/1.9 should mention guidelines for translated messages. In particular, when to use single quote and double quote (see discussion in bug 147075). It should also suggest that error messages not go into too much implementation detail or use technical language that end users will not typically understand. Also, I think the details of guideline 1.9 are incorrect. We never show details such as plug-in id and version in error dialogs. Perhaps this intended to say that errors in the log file should have those details (John Arthorne)

I think the details in 1.9 are correct, it is a ready for websphere guideline I seem to remember. It does however only refer to programming errors and not user errors. Maybe the text should be a bit more explicit about what is meant by programming errors. If your application is just about to die with a null pointer exception it should tell the user exactly what piece of code did it. (Phill Perryman)

Typo

In the past commands were called actions and someone has done a global replace of action for command but not changed the "an" to an "a" so it now reads "an command" throughout the article instead of "a command". (Phill Perryman)

Fixed in 2.1 document.

UI Graphic resources

Can you please include the colour palette file or links to them. Re-creating the full 256 colour palette by hand would be difficut to ay the least. Also my Eclipse (3.2) uses more than 2 colours for disabled icons and I can's seem to see any non colour enabled icons. Likewise your screen captures show non colour icons so do not look like the 3.2 Eclipse. Don't forget a link to the palette in 2.9 as well. Not sure what 2.15 means I only see colour and disabled icons.(Phill Perryman)

Added to 3.x document. See UI Graphics section.

UI Text : Colons

Guideline 1.6 (sentence style) it does not mention that eclipse almost always adds a colon to the end of its labels when they prefix a control such as text or combo and that postfix labels have no terminator.(Phill Perryman)

Error Handling (1.8)

The error messages are often not helpful. Some guidelines for actually writing error messages would improve consistency and usability. For example:
Explain when to use a plain message dialog, and when to add details. Is the expandable details section for recovery suggestions, or should it be used for log errors? (In Microsoft error messages, the details are usually very technical details)
Messages should say what is wrong and always suggest what can be done to fix it.
Error messages should identify the component from which it was issued when the user has to seek additional help - complete failure.
Don't blame the user for the error.
Write complete sentences.

BAD: You don't have enough memory to perform this action. DETAILS>> Action Aborted
BETTER: There is insufficient memory to save this file. Increase the available memory by deleting temporary files or removing unused programs. === Sue Yeshin syeshin@ca.ibm.com

Note on taking screencaptures for the guidelines:

Guideline 5.3, 5.4, 5.5, 5.12 (more).... - These guidelines have screen captures that do not have punctuation after the description or error sentences. When choosing examples, they need to show best practices for all the guidelines. I can help find replacement screen caps. Sue Yeshin syeshin@ca.ibm.com

Guidelines 3.4 and 3.5 contradict each other so should probably be a single recommendation with 3.4 having a providing... clause at the end.(Phill Perryman)

Limit Context Menus

This section of the guidelines makes sense...until you try realize that the context menus are not really under control of any one author or the user. For editors at least, these menus are built up from the editor code itself and plugin contributions. The plugin contributions are to each editor individually: the final set of menu items depends upon the relative age of the editor and plugins that contribute menu items. A new editor will have the menus designed by the editor author; over time plugin developers may realize the new editor exists and add their contributions. The poor user gets context menus which are inconsistent between file types and across time as plugins are added or updated.

I think the control over context menus should be given to users, not editor or plugin authors. Users should be able to select a set of global (all file types) entries and configure each context for type-specific entries. If the configurations could be exported and imported as text, users could share and eventually a few best-practice configurations would emerge. --Johnjbarton.johnjbarton.com 20:54, 20 October 2006 (EDT)

Capitalization

New Topics

Links and Buttons

Given the increasing use of hyperlinks in Eclipse, I was wondering if it would be appropriate to establish some guidelines as to their use. There seems to be two general uses, as traditional hyperlinks to navigate to a different location (for example, the File Assocations, Content Types and Appearance links on the General->Editors preference page) and to open dialogs/wizards (for example, the Configure Project Specific Settings... link on the Java->Compiler preference page). My specific area of confusion lies in the latter use case, its not clear to me under what circumstances I should be using a button and under what circumstances I should be using a hyperlink. If you could provide a guideline to go by, that'd be greatly appreciated.

Properties View

Common Error Messages

Use the common structure of error messages to help users diagnose and recover from errors. This will document and leverage the new error message framework in Eclipse v3.3. bug 173937 has been created to track this.