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 "Eclipse Doc Checklist"

(General Notes)
 
(8 intermediate revisions by 4 users not shown)
Line 3: Line 3:
 
== General Notes ==
 
== 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 Galileo site, Select the "Web Standard Tools" feature).
+
* 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]]
+
* 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 ==
 
== User Documentation ==
Line 40: Line 44:
 
** Link old topics to new topics where appropriate
 
** 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
 
** 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
 
* Review and complete extension point descriptions in the schemas
 
* Complete the What's New section
 
* 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 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.5 are marked "Since 3.5" (or whatever version is applicable for your plug-in)
+
* 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
 
* Update migration guide
** Redo screen shots if necessary
+
* Redo screen shots if necessary
  
 
== Code ==
 
== Code ==
Line 58: Line 63:
  
 
* Update the eclipse_readme.html document
 
* Update the eclipse_readme.html document
* Ensure there are no mixed line delimiters
+
* 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
 
* Check the whole doc with a link checker tool
  
 
----
 
----
 
Back to [[Eclipse Documentation]].
 
Back to [[Eclipse Documentation]].

Latest revision as of 04:19, 8 January 2019

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.

Back to the top