OpenOffice.org
Specification Guide

Author

Christian Jansen

Revision History		
Version	Description	Date
0.1	Initial Draft	August 25, 2003

Contents

1	This Document	3

2	Specifications in General	3

2.1	What is a Specification	3

3	Writing a Specification	3

3.1	Cover Everything	3

3.2	Consistency	4

3.3	Proposals vs. Specification	4

3.4	Which Brand?	4

3.5	Screen Shots, Mockups	4

3.6	Table of Contents	4

4	Specification Reviews and Feedback	4

4.1	When is a Specification Final?	5

4.2	Where to Save	5

4.2.1	Saving and Publishing Specifications on OpenOffice.org	5

4.3	Where to announce?	5

5	Content of a Specification	6

6	Resources	6

This Document

This document provides a checklist for writing a specification. It is not meant as template for specifications. If you need a specification template, please use the document located here.

The document contains the following five chapters:

Specifications in General

Explains shortly what a specification is and who is going to write a specification.

Writing a Specification

This chapter provides general tips for writing specification.

Content of a Specification

Provides the link to the specification template. The specification template also contains short descriptions of what each chapter has to contain.

Resources

List of interesting resources for creating specifications.

Specifications in General

What is a Specification

Specifications could be seen as the blueprint for a feature or bug fix. The specification describes how a feature has to work or to look. Ideally, all questions are answered before start programming it. Another benefit is that since a specification is approved by the whole i-Team, there will be nothing else build as what expected.

Writing a Specification

Below you will find some general tips before using the specification template.

Cover Everything

Make sure you've written about every single Aspect of the feature. Don't leave anything to guess or assume. When you came to a point where you believe that you covered everything give the specification to the audience (normally the i-Team) and gather their feedback (the review process is described in chapter 3. 6 ). Through this process it will be ensured that all questions will be answered and ideally everything will have a detailed description of what the feature does and how the user experience is.

Consistency

Try to write shortly. The audience will be happy. It also helps the audience if your are going to break things into logical components or steps as much as possible. Make sure you're using consistent terms (e.g., if you use “Drop down menu” in one part of the specification, don't use the term “pull down menu” in another part meaning the same thing).

Proposals vs. Specification

For development we only use specifications, proposals have the problem that the meaning of the document type is too unclear. On the other hand a proposal could be the first step to a specification. How ever the proposal can be be used for writing the specification but it is recommended to write the specification from the scratch. This makes it save that the specification contains no terms like could, should or would. A specification has to use terms like has, shall, must. More information for using shall, must etc can be found at: http://www.faqs.org/ftp/rfc/rfc2119.txt

Which Brand?

In general specifications contain the brand OpenOffice.org. A recommended style is to write Product name and Version number. For example OpenOffice.org Writer 2.0.

Screen Shots, Mockups

Screen shots help very well to give an idea of how the specified user interface will look like. Use them as many as needed. Mockups are user interface designs which look like real word dialogs, they can easily build with application like Adobe Photoshop, Jasc PaintShop or The Gimp.

Table of Contents

This is an obvious one, but make sure the table of contents shows exactly with what's in the specification. Due to the fact that the Table of Content (TOC) updates in StarOffice not automatically please place the curser in the TOC and choose “Update Index/Table” in the context menu.

Specification Reviews and Feedback

The specifications have to be reviewed by a team which works on the specific feature.

User Experience

Quality Assurance

Documentation

Development

A review will cause changes, be also prepared to give reasons why everything is written as it is. Part of the review process is to come to a solution which has the best user experience and fits best to the product. After review be sure that all mockups are up to date or if necessary update these. Be careful that the changes caused by a review don't effect other functionality. If possible prepare a second review, after all changes from the first review, have been inserted.

It is very helpful to use, for a specification review, the Redlining functionality of StarOffice (Edit – Changes ...) Adding changes or comment with Redlining enabled makes it easier for the author to see the comments.

The specification reviewers have to add their name into the version history of the specification. The version history is located at the beginning of the specification.

For feedback the Redlining functionality is a great tool. It is recommended to place the feedback directly in to chapter where the reviewer wants to give feedback.

When is a Specification Final?

A specification is final if all reviews are done, including the string review and the check if the specification covers the needs resulting out of the requirements. All suggested changes are included into the specification and the mock-ups must also be up to date.

If all changes are in the specification it changes its state to “Final” this has to be documented in the Document History Table located at the beginning of the specification.

Sometimes it is necessary to make small after the specification got final, if so please add a date and a shot comment in the Document History Table.

What is is if a feature will be revised in a upcoming version? In this case a new specification has to be written. The new specification has to contain a link to the original specification. The the link has to be stated into the references chapter.

Where to Save

Saving and Publishing Specifications on OpenOffice.org

Specifications have to be saved by using CVS (CVS is a version control system) on OpenOffice.org. OpenOffice.org has its own project for specifications which is called “Specification Project”. The URL of the “Specification Project” is http://specs.openoffice.org. For saving specifications on specs.openoffice.org you need write access to the server. If you want to have write access please contact the project lead Christian Jansen (cj@openoffice.org).

Where to announce?

When the specification is final it has to be announced on a mailing list called

announce@specs.openoffice.org

The announcement has to give some information about the specifications and should cover the topics listed below.

Specification title Link(s) to the specification document(s)

Status (draft / version x / final)

Modifications

Comment

Feedback to:

Please also update the specification announcement if significant changes were done in the specification. Add in this case a small description of what was changed.

Content of a Specification

The content of a specification is described in detail in the specification template.

Resources

Specification Template - the StarOffice Specification Template

RFC2119 – Usage of shall, must etc.

Adobe Photoshop – The best pixel graphic editing tool

PaintShop – Another pixel editing tool

The Gimp – An open source image manipulation tool.

CVS – Version Management with CVS

CVS – Examples

TortoiseCVS – A Windows Explorer CVS extension

StarOffice Specification Workflow

Page 6

StarOffice Specification Workflow

Christian Jansen

2002-08-08T10:58:40

Christian Jansen