Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between revisions of "Architecture Council/New and Noteworthy"

(New page: An excellent way to communicate about your project milestones and releases is via a "New & Noteworthy" document. Such a document allows a new user or someone upgrading from a previous rele...)
 
(Links)
 
(7 intermediate revisions by 2 users not shown)
Line 1: Line 1:
An excellent way to communicate about your project milestones and releases is via a "New & Noteworthy" document. Such a document allows 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.
+
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 ==
 
== Format ==
  
* Simple HTML is the more 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 [http://help.eclipse.org/ganymede/topic/org.eclipse.platform.doc.user/whatsNew/platform_whatsnew.html What's new] section in the Workbench User Guide for example).
+
* 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 [http://help.eclipse.org/ganymede/topic/org.eclipse.platform.doc.user/whatsNew/platform_whatsnew.html 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 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
 
* Provide at least one "printer-friendly" page with all content on a single page
Line 10: Line 10:
 
== Content ==
 
== 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
 
* 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 ==
  
[category: Architecture Council]
+
* For an example, see the Eclipse project's [http://download.eclipse.org/eclipse/downloads/drops/R-3.4-200806172000/whatsnew3.4/eclipse-news.html New and Noteworthy] document
[category: Best Practices]
+
* See the Eclipse project's New & Noteworthy [http://dev.eclipse.org/mhonarc/lists/eclipse-dev/zipgzGX2M1lXg.zip template].
 +
 
 +
[[Category:Architecture Council|New and Noteworthy]]
 +
[[Category:Best Practices|New and Noteworthy]]

Latest revision as of 14:47, 2 September 2009

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

Back to the top