Difference between revisions of "The Three Golden Rules for Writing OpenOffice.org Specifications"

From Apache OpenOffice Wiki
Jump to: navigation, search
m (R1 [COMPLETE]:)
m (R1 [COMPLETE]:)
Line 17: Line 17:
 
* Are the topics of the [http://specs.openoffice.org/collaterals/guides/collaterals/guides/I18n_in_Software.html Globalization Checklist ] covered?
 
* Are the topics of the [http://specs.openoffice.org/collaterals/guides/collaterals/guides/I18n_in_Software.html Globalization Checklist ] covered?
 
* Are the topics of the [http://specs.openoffice.org/collaterals/guides/collaterals/guides/text-style-guide.html Interface Text Style Guide checklist] covered?
 
* Are the topics of the [http://specs.openoffice.org/collaterals/guides/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 - Comprehensive OpenOffice.org Menu specification?
+
* 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 - Comprehensive OpenOffice.org Tool bar specification?
+
* Are all tool bar related changes specified in the [http://specs.openoffice.org/appwide/toolbars/Toolbar_content_spec.sxw 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?

Revision as of 09:17, 7 March 2006

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:

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”?


Category:Specification

Personal tools