Eclipse Doc Checklist

This checklist can be used to ensure that all documentation work for a component gets completed. You may find it useful to make a copy of this page for your component, adding extra items that are specific for you, and checking items off as they are completed.

General Notes

• Make sure you use an HTML editor that will not munge the documentation source. Good examples are the Eclipse text editor, or the HTML editor in WTP (Help > Install New Software, select the matching Simultaneous Release site, select the "Web Page Editor" feature).
• Make sure new additions and changes adhere to the Eclipse Doc Style Guide.
• In most cases, we will want to be sure a document is "touched" near the release. The reason is that if Javadoc or extension point documentation changes (in other bundles) it will not automatically cause the qualifier of the "doc bundle" to increment, so a previous (out-of-date) version of the doc bundle will be included in the distribution, instead of the freshly built one. Note that committers can do this "touch" any time they like (or, arrange for it to be done), if they make substantial changes and want to check the end result in a "built" version of the bundle, but we do not normally do anything systematic for milestones, etc. But, for the 'release' we should be systematic about it, just to be sure the latest Javadoc and extension point documentation is included in the released version. Bundles to be touched for SDK releases:
  • org.eclipse.platform.doc.isv
  • org.eclipse.jdt.doc.isv
  • org.eclipse.pde.doc.user

User Documentation

• For all existing user documentation:
  • Remove/correct out-dated contents
  • Ensure that the contents of the topic are appropriate for the category the topic is in
  • Redo screen shots if necessary
• For significant new features in the current release:
  • Add Concepts and Tasks entries
  • Search the existing help topics for other pages that relate to the topic you are writing about and add them as "Related <topic>" links
• Check all views and editors in the new dynamic Help view
  • Ensure summary is correct
  • Ensure links work and make sense
• Check all dialogs and wizards to ensure that the (?) button or F1 shows relevant information
• Getting Started section:
  • Make sure the Platform Getting Started section is of high-quality and easy to read
  • Test the Platform getting started: go through it step by step
• Update the Tips & Tricks document
• Complete the What's New section
• Update the list of used icons
• Check all examples and corresponding example descriptions
• Ensure command line arguments under Tasks > Running Eclipse are updated and correct
• Ensure Reference > User interface information is updated
  • New wizards are listed
  • New dialogs are listed
  • New views and editors are listed
  • New icons are listed in the "Icons and buttons" section

ISV Documentation

• For significant new API in the current release:
  • Add Programmer's Guide entries
  • Link new topics to related concepts and tasks in the user guide
  • Link old topics to new topics where appropriate
  • Search the existing help topics for other pages that relate to the topic you are writing about and consider adding them as "Related <topic>" links
• Verify new Java versions are listed under "Using the batch compiler" section.
• Review and complete extension point descriptions in the schemas
• Complete the What's New section
• Verify that all APIs and extension-points appear in the Reference section (see How to add things to the Eclipse doc)
• Verify that extension points added in 3.7 are marked "Since 3.7" (or whatever version is applicable for your plug-in)
• Update migration guide
• Redo screen shots if necessary

Code

• Javadoc
  • Verify that all APIs have Javadoc
  • Check spelling (use American English)
  • Ensure new APIs have the @since tag with correct version number for your bundle
• spell check all *.properties files (use American English)

Miscellaneous

• Update the eclipse_readme.html document
• Ensure there are no mixed line delimiters by doing a search with the following regex (compiled by Markus):

(?s)(\r\n[^\n]*+(?<!\r)\n)|(\r\n[^\r]*+\r(?!\n))|(\r[^\n][^\n]*+\n)|([^\r]\n[^\r\n]*+\r)

• Check the whole doc with a link checker tool

---

Back to Eclipse Documentation.