| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> |
| <html> |
| <head> |
| |
| |
| <meta http-equiv="CONTENT-TYPE" content="text/html; charset=windows-1252"> |
| <title></title> |
| <meta name="GENERATOR" content="StarOffice 8 (Win32)"> |
| |
| |
| <meta name="AUTHOR" content="Christian Jansen"> |
| |
| |
| <meta name="CREATED" content="20051012;16182200"> |
| |
| |
| <meta name="CHANGEDBY" content="Tino Rachui"> |
| |
| |
| <meta name="CHANGED" content="20051024;20261800"> |
| |
| |
| <meta name="SDFOOTNOTE" content=";;;;P"> |
| |
| |
| <meta name="SDENDNOTE" content="ARABIC"> |
| </head> |
| |
| |
| <body dir="ltr" lang="en-US" text="#000000"> |
| <div align="left"> |
| <h2>Rules for Writing Software Specifications</h2> |
| </div> |
| <table border="0" bgcolor="black" bordercolor="#000000" cellpadding="2" cellspacing="1" width="100%"> |
| |
| <col width="205"> |
| <col width="206"> |
| <col width="205"> |
| <thead> |
| <tr valign="top"> |
| |
| <th bgcolor="white" width="205"> |
| |
| <p style="font-style: normal;" align="left">Owner:<br> |
| Christian |
| Jansen</p> |
| |
| </th> |
| |
| <th bgcolor="white" width="206"> |
| |
| <p style="font-style: normal;" align="left">Last |
| Change:<br> |
| December 22, 2005</p> |
| |
| </th> |
| |
| <th bgcolor="white" width="205"> |
| |
| <p style="font-style: normal;" align="left">Status:<br> |
| |
| Preliminary</p> |
| |
| </th> |
| |
| </tr> |
| |
| </thead> |
| <tbody> |
| |
| <tr> |
| |
| <td colspan="3" valign="top" bgcolor="white" width="636"> |
| |
| <p align="left"><b>Goal |
| of this document:<br> |
| </b> |
| This |
| rule set assists specification authors creating specifications. |
| It captures the essential specification rules that have to be |
| followed.</p> |
| |
| </td> |
| |
| </tr> |
| |
| <tr> |
| |
| <td colspan="3" valign="top" bgcolor="white" width="636"> |
| |
| <p align="left"><b>Intended |
| readership:<br> |
| </b>Specification authors, specification reviewers (Development , Quality Assurance , User Experience, Documentation)</p> |
| |
| </td> |
| </tr> |
| <tr> |
| <th colspan="3" valign="top" bgcolor="white" width="636"><p align="left">Send Feedback to:<br> |
| <a href="mailto:dev@specs.openoffice.org">dev@specs.openoffice.org<br> |
| </a></p> |
| </th> |
| |
| </tr> |
| |
| |
| </tbody> |
| </table> |
| <p align="left">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'.</p> |
| <h3 align="left">R1 [COMPLETE]:</h3> |
| <p align="left">First and foremost a specification has to be complete. That means all relevant aspects of a feature have been captured.</p> |
| <p align="left">When user interfaces (UI) are |
| involved: |
| </p> |
| <ul> |
| <li>Are the topics of the <a href="../guides/Accessibility-checklist.html"><img src="../guides/images/Rules-for-Writing-OpenOffice.org-Specifications_html_d4e38e3.gif" name="Grafik1" align="bottom" border="0" height="14" width="16">Accessibility Checklist</a> covered?<li>Are the topics of the <a href="../guides/I18n_in_Software.html"><img src="../guides/images/Rules-for-Writing-OpenOffice.org-Specifications_html_d4e38e3.gif" name="graphics1" align="bottom" border="0" height="14" width="16">Globalization Checklist</a> covered?<li>Are the topics of the <img src="../guides/images/Rules-for-Writing-OpenOffice.org-Specifications_html_d4e38e3.gif" name="graphics2" align="bottom" border="0" height="14" width="16"><a href="../guides/_components.inv/UITextStyleGuide.html#Checklist">OpenOffice.org Interface Text Style Guide</a> checklist covered?<li>Do alerts meet the requirements specified in the <a href="../guides/Alert-Guidelines.html"><img src="../guides/images/Rules-for-Writing-OpenOffice.org-Specifications_html_d4e38e3.gif" name="graphics3" align="bottom" border="0" height="14" width="16"> Alert Guidelines</a>?<li>Are all menu related changes specified in the <a href="http://specs.openoffice.org/appwide/menus/MenuStructure.sxw"><img src="../guides/images/Rules-for-Writing-OpenOffice.org-Specifications_html_d4e38e3.gif" name="graphics4" align="bottom" border="0" height="14" width="16"> </a><a href="http://specs.openoffice.org/appwide/menus/MenuStructure.sxw">Comprehensive OpenOffice.org Menu specification</a>?<li>Are all tool bar related changes specified in the <a href="http://specs.openoffice.org/appwide/toolbars/Toolbar_content_spec.sxw"><img src="../guides/images/Rules-for-Writing-OpenOffice.org-Specifications_html_d4e38e3.gif" name="graphics5" align="bottom" border="0" height="14" width="16"></a><a href="http://specs.openoffice.org/appwide/toolbars/Toolbar_content_spec.sxw"> Comprehensive OpenOffice.org Tool bar specification</a>?<li>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)? |
| |
| |
| <li>Is the exception handling specified in detail? |
| |
| |
| </ul> |
| <h3 align="left">R2 [CLEAR]:</h3> |
| <ul> |
| <li>Each statement has to be unambiguously clear to Development , Quality Assurance, USer Experience and Documentation. |
| <li>Is the specification in itself clear enough to the intended readership for being implemented, being tested and for being documented?<br> |
| <li>Are you using quantifiable statements instead of interpretable generalities? |
| <li>Have you avoided to use terms like more, most, less, easy, improve, enhanced, better? |
| <li>Are you consistent within the specification and to specifications which relate to the feature you are specifying?</ul> |
| <h3 align="left">R3 [SIMPLE]:</h3> |
| <ul> |
| <li>Each statement shall be as short and simple as possible. |
| </ul> |
| <p align="left">Is any secondary writing regarding the |
| detailed specification clearly separated e.g. “comments”, |
| “notes”, “suggestions”, “ideas”, |
| “reasons”?</p> |
| <p align="left"></p> |
| <p align="left"></p> |
| <p align="left"><b>Document History:</b></p> |
| <table border="0" bgcolor="black" bordercolor="#000000" cellpadding="2" cellspacing="1" width="100%"> |
| |
| <col width="54"> |
| <col width="383"> |
| <col width="51"> |
| <col width="121"> |
| <thead> |
| <tr valign="top"> |
| |
| <td bgcolor="white" width="54"> |
| <div align="center"> |
| <p><b>Revision</b></p> |
| </div> |
| </td> |
| |
| <td bgcolor="white" width="594"> |
| <p><b>Change</b></p> |
| </td> |
| |
| <td bgcolor="white" width="51"> |
| <p><b>Initials</b></p> |
| </td> |
| |
| <td bgcolor="white" width="121"> |
| <p><b>Date</b></p> |
| </td> |
| |
| </tr> |
| |
| </thead> |
| <tbody> |
| |
| <tr valign="top"> |
| |
| <td bgcolor="white" width="54"> |
| <div align="center"> |
| <p>1</p> |
| </div> |
| </td> |
| |
| <td bgcolor="white" width="594"> |
| <p>First draft created</p> |
| </td> |
| |
| <td bgcolor="white" width="51"> |
| <p>CJ/TRA</p> |
| </td> |
| |
| <td bgcolor="white" width="121"> |
| <p>June 8, 2005</p> |
| </td> |
| |
| </tr> |
| |
| <tr valign="top"> |
| |
| <td bgcolor="white" width="54"> |
| <div align="center"> |
| <p>2</p> |
| </div> |
| </td> |
| |
| <td bgcolor="white" width="594"> |
| <p>Reviewed by Jörg Sievers</p> |
| </td> |
| |
| <td bgcolor="white" width="51"> |
| <p>JSI</p> |
| </td> |
| |
| <td bgcolor="white" width="121"> |
| <p>June 8, 2005</p> |
| </td> |
| |
| </tr> |
| |
| <tr valign="top"> |
| |
| <td bgcolor="white" width="54"> |
| <div align="center"> |
| <p>3</p> |
| </div> |
| </td> |
| |
| <td bgcolor="white" width="594"> |
| <p>Based on feedback rules revised</p> |
| </td> |
| |
| <td bgcolor="white" width="51"> |
| <p>CJ/TRA</p> |
| </td> |
| |
| <td bgcolor="white" width="121"> |
| <p>June 9, 2005</p> |
| </td> |
| |
| </tr> |
| |
| <tr valign="top"> |
| |
| <td bgcolor="white" width="54"> |
| <div align="center"> |
| <p>4</p> |
| </div> |
| </td> |
| |
| <td bgcolor="white" width="594"> |
| <p>Merged rules and checklist questions</p> |
| </td> |
| |
| <td bgcolor="white" width="51"> |
| <p>CJ/TRA</p> |
| </td> |
| |
| <td bgcolor="white" width="121"> |
| <p>July 18, 2005</p> |
| </td> |
| |
| </tr> |
| |
| <tr valign="top"> |
| |
| <td bgcolor="white" width="54"> |
| <div align="center"> |
| <p>5</p> |
| </div> |
| </td> |
| |
| <td bgcolor="white" width="594"> |
| <p>Based on inspection rules & header revised</p> |
| </td> |
| |
| <td bgcolor="white" width="51"> |
| <p>CJ</p> |
| </td> |
| |
| <td bgcolor="white" width="121"> |
| <p>September 30, 2005</p> |
| </td> |
| |
| </tr> |
| |
| <tr valign="top"> |
| |
| <td bgcolor="white" width="54"> |
| <div align="center"> |
| <p>6</p> |
| </div> |
| </td> |
| |
| <td bgcolor="white" width="594"> |
| <p>Header revised</p> |
| </td> |
| |
| <td bgcolor="white" width="51"> |
| <p>CJ</p> |
| </td> |
| |
| <td bgcolor="white" width="121"> |
| <p>October 10, 2005</p> |
| </td> |
| |
| </tr> |
| |
| <tr valign="top"> |
| |
| <td bgcolor="white" width="54"> |
| <div align="center"> |
| <p>7</p> |
| </div> |
| </td> |
| |
| <td bgcolor="white" width="594"> |
| <p>R1 revised,R3 revised, Links added</p> |
| </td> |
| |
| <td bgcolor="white" width="51"> |
| <p>CJ</p> |
| </td> |
| |
| <td bgcolor="white" width="121"> |
| <p>October 19, 2005</p> |
| </td> |
| |
| </tr> |
| <tr valign="top"> |
| <td bgcolor="white" width="54"> |
| <div align="center"> |
| <p>8</p> |
| </div> |
| </td> |
| <td bgcolor="white" width="594"> |
| <p>Made doc OpenOffice.org compliant</p> |
| </td> |
| <td bgcolor="white" width="51"> |
| <p>CJ</p> |
| </td> |
| <td bgcolor="white" width="121"> |
| <p>December 22, 2005</p> |
| </td> |
| </tr> |
| <tr valign="top"> |
| <td bgcolor="white" width="54"> |
| <div align="center"> |
| 9</div> |
| </td> |
| <td bgcolor="white" width="594">Reviewed by CJ/TRA</td> |
| <td bgcolor="white" width="51">CJ/TRA</td> |
| <td bgcolor="white" width="121">December 29, 2005</td> |
| </tr> |
| </tbody> |
| </table> |
| </body> |
| </html> |
