Jump to: navigation, search

Difference between revisions of "Eclipse Doc Checklist"

m
(14 intermediate revisions by 2 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 > Software Updates > Find new features to Install > Callisto Discovery Site > Select the "Web Standard Tools" feature and click "Select Required").
+
* 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 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]]
  
 
== User Documentation ==
 
== User Documentation ==
  
* Go through all documentation and remove/correct all out-dated contents
+
* For all existing user documentation:
* Add Concepts and Tasks entries for significant new features
+
** 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
 
* Check all views and editors in the new dynamic Help view
 
** Ensure summary is correct
 
** Ensure summary is correct
Line 18: Line 23:
 
** Test the Platform getting started: go through it step by step
 
** Test the Platform getting started: go through it step by step
 
* Update the Tips & Tricks document
 
* Update the Tips & Tricks document
* Complete the What's New in 3.2 section
+
* Complete the What's New section
* Update the list of used icons [Martin]
+
* Update the list of used icons
 
* Check all examples and corresponding example descriptions
 
* Check all examples and corresponding example descriptions
 
* Ensure command line arguments under Tasks > Running Eclipse are updated and correct
 
* Ensure command line arguments under Tasks > Running Eclipse are updated and correct
 +
* Ensure Reference &gt; 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 ==
 
== 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
 
* Review and complete extension point descriptions in the schemas
 
* Review and complete extension point descriptions in the schemas
* Verify that all APIs and extension-points appear in the corresponding programmer's guide (see [[How to add things to the Eclipse doc]])
+
* Complete the What's New section
* Verify that extension points added in 3.2 are marked "Since 3.2"
+
* 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
 
* Update migration guide
 +
* Redo screen shots if necessary
  
 
== Code ==
 
== Code ==
Line 35: Line 52:
 
** Verify that all APIs have Javadoc
 
** Verify that all APIs have Javadoc
 
** Check spelling (use American English)
 
** Check spelling (use American English)
** Ensure new APIs have the @since3.2 tag
+
** Ensure new APIs have the @since tag with correct version number for your bundle
 
* spell check all *.properties files (use American English)
 
* spell check all *.properties files (use American English)
* Verify that component.xml files are correct
 
  
 
== Miscellaneous ==
 
== Miscellaneous ==
  
 
* Update the eclipse_readme.html document
 
* Update the eclipse_readme.html document
* Ensure there are no mixed line delimiters [Dani]
+
* 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]*+\r)
* Redo screen shots if necessary
+
 
* 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]].

Revision as of 09:14, 18 May 2011

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 Galileo site, select the "Web Page Editor" feature).
  • Make sure new additions and changes adhere to the Eclipse Doc Style Guide

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
  • 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]*+\r)
  • Check the whole doc with a link checker tool

Back to Eclipse Documentation.