The Three Golden Rules for Writing Specifications

From Apache OpenOffice Wiki
Revision as of 17:28, 23 February 2009 by TJFrazier (Talk | contribs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

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'.


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:


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


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

Personal tools