Difference between revisions of "The Three Golden Rules for Writing OpenOffice.org Specifications"
From Apache OpenOffice Wiki
m |
(→R1 [COMPLETE]:: bad link toolbar spec, sxw->odt) |
||
| (12 intermediate revisions by 4 users not shown) | |||
| Line 6: | Line 6: | ||
<br> | <br> | ||
'''Send Feedback to:'''<br> | '''Send Feedback to:'''<br> | ||
| − | + | dev at specs dot openoffice dot org <br> | |
| − | + | ||
| − | + | ---- | |
Each of the following rules [R] is accompanied by a couple of checklist questions. The optimum is to answer all of the questions with 'Yes'. | Each of the following rules [R] is accompanied by a couple of checklist questions. The optimum is to answer all of the questions with 'Yes'. | ||
| Line 14: | Line 14: | ||
First and foremost a specification has to be complete. That means all relevant aspects of a feature have been captured. | First and foremost a specification has to be complete. That means all relevant aspects of a feature have been captured. | ||
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 | + | * Are the topics of the [http://specs.openoffice.org/collaterals/guides/I18n_in_Software.html Globalization Checklist] covered? |
| − | Are the topics of the | + | * Are the topics of the [http://specs.openoffice.org/collaterals/guides/text-style-guide.html Interface Text Style Guide checklist] covered? |
| − | Do alerts meet the requirements specified in the - Alert Guidelines? | + | * 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 Comprehensive 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.odt Comprehensive OpenOffice.org Tool bar 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? |
| + | |||
=== R2 [CLEAR]: === | === R2 [CLEAR]: === | ||
| − | Each statement has to be unambiguously clear to Development , Quality Assurance, | + | * Each statement has to be unambiguously clear to Development , Quality Assurance, User Experience and Documentation. |
| − | Is the specification in itself clear enough to the intended readership for being implemented, being tested and for being documented? | + | * Is the specification in itself clear enough to the intended readership for being implemented, being tested and for being documented? |
| + | |||
| + | * Are you using quantifiable statements instead of interpretable generalities? | ||
| + | * 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? | ||
| − | |||
| − | |||
| − | |||
=== R3 [SIMPLE]: === | === R3 [SIMPLE]: === | ||
| − | Each statement shall be as short and simple as possible. | + | * Each statement shall be as short and simple as possible. |
| + | <br> | ||
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”? | ||
| + | |||
| + | |||
| + | [[Category:Specification]][[Category:Quality Assurance]] | ||
Latest revision as of 17:28, 23 February 2009
Goal of this document:
These three rules shall assist specification authors writing specifications.
Intended readership:
Specification authors, specification reviewers (Development , Quality Assurance , User Experience, Documentation
Send Feedback to:
dev at specs dot openoffice dot org
Each of the following rules [R] is accompanied by a couple of checklist questions. The optimum is to answer all of the questions with 'Yes'.
R1 [COMPLETE]:
First and foremost a specification has to be complete. That means all relevant aspects of a feature have been captured. When user interfaces (UI) are involved:
- Are the topics of the Accessibility Checklist covered?
- Are the topics of the Globalization Checklist covered?
- Are the topics of the Interface Text Style Guide checklist covered?
- Do alerts meet the requirements specified in the Alert Guidelines?
- Are all menu related changes specified in the Comprehensive OpenOffice.org Menu specification?
- Are all tool bar related changes specified in the Comprehensive OpenOffice.org Tool bar 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?
R2 [CLEAR]:
- Each statement has to be unambiguously clear to Development , Quality Assurance, User Experience and Documentation.
- Is the specification in itself clear enough to the intended readership for being implemented, being tested and for being documented?
- Are you using quantifiable statements instead of interpretable generalities?
- 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?
R3 [SIMPLE]:
- 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”?
