Eclipse "New and Noteworthy" Template

Last revised 2012-11-02.

This is the template for the "New and Noteworthy" document that accompanies each Eclipse project milestone build.

Note: This template document is XHTML 1.0 Transitional. Please use the W3C XHTML Markup Validation Service to check your document's markup before submitting. This will detect screwed up HTML tags, images without an "alt" attribute, and other tedious little details.

Instructions
Item title, in sentence style, no trailing punctuation, with unique id attribute on <tr> A blurb pitched to the Eclipse community (not just to members of the Eclipse Platform development team). Tell end users about changes they'll see in the UI. Tell component writers about changes they'll see at the client- and server-side APIs. Try to generate some excitement; save the boring details for the manual; be short and don't repeat yourself. The description should be complete sentences, with trailing punctuation.

Use active voice (say "you", not "the user"), and follow other advice in the Topic Content section of the Eclipse Doc Style Guidelines.

Stick to the default font and size. Make command names (Quick Fix), keyboard shortcuts (Ctrl+1), and preference page paths (Preferences > General > Keys) bold.

Do not enclose the first paragraph of an item in <p></p> tags.

Screenshots If a small image sheds light, place it below the description, in a separate paragraph. Regular screen snapshots should be done on Windows 7. Crop out any extraneous stuff to focus the reader's attention on your new feature. The image should be no more than 519 pixels wide and in PNG format (as opposed to GIF, TIF, BMP, or JPG). Use PNG-8 if your image doesn't have a lot of color, or PNG-24 if the screen shot uses enough color to warrant additional color depth. See also the Graphics section of the Eclipse Doc Style Guidelines.

The Windows Snipping Tool actually saves to PNG on Windows 7 and can easily be used to crop and save screenshots:

  • Arrange the windows for the shot
  • Use the Windows Snipping Tool to capture part of the screen
  • Use File > Save As to save the screenshot as a PNG
  • Overlays such as red circles or boxes to call out details can be done using Microsoft Paint

Name the file is a way that is appropriate and specific to the item (e.g., key-bindings.png, rather than something generic like image.png). Use all lowercase letters in the image file name, including the ".png" file extension. As a separator, use hyphen "-" rather than underscore "_".

Put all the images in a sibling directory named "images". This gives XHTML like:
<img src="images/foo-view.png" alt=""/>
Include a suitable alt attribute. The alt text should be empty ("") if the image just illustrates the text. Only use the alt text to add information that is not accessible if the page is rendered without images. Don't write alt="Screenshot of the XY dialog". Blind users shouldn't have to skip useless repetitions.

If the alt attribute text cannot sufficiently replace the image contents (e.g. for a screenshot that shows source code), then enclose the img element in a link to a plain ".txt" file with the same name as the image:
<a href="images/foo-view.txt"><img ...

The images should be left-justified (as opposed to centered). Do not embed the width and height of the image.

Use the W3C XHTML Markup Validation Service to check your document's markup before submitting.

Platform
First item Item blurb.
Second item Item blurb.

JDT
First item Item blurb.

PDE
First item Item blurb.

Equinox
First item Item blurb.