Architecture Council/New and Noteworthy

An excellent way to communicate about your project milestones and releases is via a "New & Noteworthy" document. Such a document gives a new user or someone upgrading from a previous release a snapshot of all the cool and interesting changes in the current release of your project. Don't underestimate how difficult it can be for project outsiders to find for themselves all the cool new things you did in a given milestone or year. The following are some guidelines or best practices on how to write a new and noteworthy document.

Format

• Simple HTML is the most versatile format. With plain HTML you can put the document up on your web site, zip it up and send it to others, and include it as content in your project's help system (see the What's new section in the Workbench User Guide for example).
• Provide anchors for every item so that bloggers and other readers can pass along a link to their favorite new feature to their friends.
• Provide at least one "printer-friendly" page with all content on a single page
• If you have a lot of content, also provide a multi-page version where there is a different page for each component/sub-project/whatever in your project.

Content

• Each item should consist of a blurb pitched to the Eclipse community (not just to members of your development team). Tell end users about changes they'll see at 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. The description should be complete sentences, with trailing punctuation. Stick to the default font and size.
• Organize items in logical groups so there is some flow for a reader who sits down to read the whole document
• Don't water down the content with lots of tiny features. You don't want to give the impression you're really stretching to come up with interesting material. Focus on the really interesting features
• If a small image sheds light, place it below the description, in a separate paragraph. Regular screen snapshots should be done on the same OS/WS for consistency. Crop out any extraneous stuff to focus the reader's attention on your new feature.

Links

• For an example, see the Eclipse project's New and Noteworthy document
• See the Eclipse project's New & Noteworthy template.