The Three Golden Rules for Writing OpenOffice.org Specifications
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@specs.openoffice.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 -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”?
