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.
Difference between revisions of "Eclipse Doc Checklist"
(→Miscellaneous: a little tweak that massively improves performance for checking \n-delimited larger files) |
|||
| (13 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 | + | * 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]] | ||
| Line 11: | Line 11: | ||
** Remove/correct out-dated contents | ** Remove/correct out-dated contents | ||
** Ensure that the contents of the topic are appropriate for the category the topic is in | ** 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: | * For significant new features in the current release: | ||
** Add Concepts and Tasks entries | ** Add Concepts and Tasks entries | ||
| Line 22: | 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 | + | * Complete the What's New section |
* Update the list of used icons | * 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 > 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 == | ||
| Line 35: | Line 41: | ||
** 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 | ||
* Review and complete extension point descriptions in the schemas | * 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 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. | + | * 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 44: | 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 @since | + | ** 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) | ||
| − | |||
== Miscellaneous == | == Miscellaneous == | ||
* 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]]. | ||
Revision as of 08:51, 27 May 2014
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\n]*+\r)
- Check the whole doc with a link checker tool
Back to Eclipse Documentation.