Rules for Writing Software Specifications
Owner: |
Last
Change: |
Status: |
---|---|---|
Goal
of this document: |
||
Intended
readership: |
||
Send Feedback to: |
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
OpenOffice.org 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”?
Document History:
Revision |
Change |
Initials |
Date |
1 |
First draft created |
CJ/TRA |
June 8, 2005 |
2 |
Reviewed by Jörg Sievers |
JSI |
June 8, 2005 |
3 |
Based on feedback rules revised |
CJ/TRA |
June 9, 2005 |
4 |
Merged rules and checklist questions |
CJ/TRA |
July 18, 2005 |
5 |
Based on inspection rules & header revised |
CJ |
September 30, 2005 |
6 |
Header revised |
CJ |
October 10, 2005 |
7 |
R1 revised,R3 revised, Links added |
CJ |
October 19, 2005 |
8 |
Made doc OpenOffice.org compliant |
CJ |
December 22, 2005 |
9
|
Reviewed by CJ/TRA | CJ/TRA | December 29, 2005 |