Difference between revisions of "Specification Template Help"
From Apache OpenOffice Wiki
(→Abstract) |
(→General) |
||
| Line 14: | Line 14: | ||
<br> | <br> | ||
| − | ; | + | ; Completeness [Rule 1] : |
First and foremost a specification has to be complete. That means all relevant aspects of a feature have to be captured. | First and foremost a specification has to be complete. That means all relevant aspects of a feature have to be captured. | ||
<br> | <br> | ||
When user interfaces (UI) are involved: | When user interfaces (UI) are involved: | ||
| − | * Are the topics of the Accessibility Checklist covered? | + | * Are the topics of the [http://specs.openoffice.org/collaterals/guides/Accessibility-checklist.html|Accessibility Checklist] covered? |
| − | * Are the topics of the Globalization Checklist covered? | + | * Are the topics of the [http://specs.openoffice.org/collaterals/guides/I18n_in_Software.html|Globalization Checklist] covered? |
| − | * Are the topics of the OpenOffice.org User Interface Text Style Guide | + | * Are the topics of the [http://specs.openoffice.org/collaterals/guides/text-style-guide.html|OpenOffice.org User Interface Text Style Guide Checklist] covered? |
| − | * Do alerts meet the requirements specified in the | + | * Do alerts meet the requirements specified in the [http://specs.openoffice.org/collaterals/guides/Alert-Guidelines.html|Alert Guidelines]? |
| − | * Are all menu related changes specified in the | + | * Are all menu related changes specified in the [http://specs.openoffice.org/appwide/menus/MenuStructure.sxw|OpenOffice.org Menu specification]? |
| − | * Are all tool bar related changes specified in the | + | * Are all tool bar related changes specified in the [http://specs.openoffice.org/appwide/toolbars/Toolbar_content_spec.sxw|OpenOffice.org Toolbar] specification? |
* Is each UI element specified in detail (e.g. default values, input and output ranges, interactions and possible relations to other UI elements and parts of the UI)? | * Is each UI element specified in detail (e.g. default values, input and output ranges, interactions and possible relations to other UI elements and parts of the UI)? | ||
* Is the exception handling specified in detail? | * Is the exception handling specified in detail? | ||
<br> | <br> | ||
| − | ; | + | ; Clarity [Rule 2] : |
Each statement has to be '''unambiguously clear''' to Development, Quality Assurance, User Experience and Documentation. | Each statement has to be '''unambiguously clear''' to Development, Quality Assurance, User Experience and Documentation. | ||
* Is the specification clear enough to the intended readership for being implemented, being tested and for being documented? | * Is the specification clear enough to the intended readership for being implemented, being tested and for being documented? | ||
| Line 36: | Line 36: | ||
<br> | <br> | ||
| − | ; | + | ; Simplicity [Rule 3] : |
Each statement shall be as short and simple as possible. | Each statement shall be as short and simple as possible. | ||
Is any secondary writing regarding the detailed specification clearly separated e.g. “comments”, “notes”, “suggestions”, “ideas”, “reasons”? | Is any secondary writing regarding the detailed specification clearly separated e.g. “comments”, “notes”, “suggestions”, “ideas”, “reasons”? | ||
| + | |||
=== Graphics & Flow-Charts === | === Graphics & Flow-Charts === | ||
'''Tip:''' | '''Tip:''' | ||
Use graphics when concepts, designs, or processes are too complex or cumbersome to describe with words. | Use graphics when concepts, designs, or processes are too complex or cumbersome to describe with words. | ||
Revision as of 09:52, 3 November 2006
Status
- Preliminary
- The specification is in concept state
- Standard
- A specification with status Standard is considered to be stable.
- Obsolete
- An Obsolete specification is a specification that has been identified unnecessary. For example due to technology changes or changes in other standards or specifications.
Abstract
The Abstract section provides a concise and comprehensive overview of the purpose and contents of the entire document. In addition to this the Abstract will serve as input for Marketing in order to prepare the to New Features. Don't use more than 150 words in the Abstract.
Detailed Specification
General
Bear in mind the following rules when writing a specification:
- Completeness [Rule 1]
First and foremost a specification has to be complete. That means all relevant aspects of a feature have to be captured.
When user interfaces (UI) are involved:
- Are the topics of the Checklist covered?
- Are the topics of the Checklist covered?
- Are the topics of the User Interface Text Style Guide Checklist covered?
- Do alerts meet the requirements specified in the Guidelines?
- Are all menu related changes specified in the Menu specification?
- Are all tool bar related changes specified in the Toolbar specification?
- Is each UI element specified in detail (e.g. default values, input and output ranges, interactions and possible relations to other UI elements and parts of the UI)?
- Is the exception handling specified in detail?
- Clarity [Rule 2]
Each statement has to be unambiguously clear to Development, Quality Assurance, User Experience and Documentation.
- Is the specification clear enough to the intended readership for being implemented, being tested and for being documented?
- Are you using quantifiable statements instead of interpretable generalities? For instance: Have you avoided to use terms like “more”, “most”, “less”, “easy”, “improve”, “enhanced”, “better”?
- Are you consistent within the specification and to specifications which relate to the feature you are specifying?
- Simplicity [Rule 3]
Each statement shall be as short and simple as possible.
Is any secondary writing regarding the detailed specification clearly separated e.g. “comments”, “notes”, “suggestions”, “ideas”, “reasons”?
Graphics & Flow-Charts
Tip:
Use graphics when concepts, designs, or processes are too complex or cumbersome to describe with words.
