Example Spec

 

Overview

How to use this template:

  1. Cut and paste all this text into a new page, and replace the place-holder text with your content. Try to answer as many of the place-holder questions as you can.
  2. Leave all headers in place. Simply insert N/A if the section does not apply.
  3. Try to keep the specification less than 10 pages or a handful of new windows. People seem to stop reading if it gets longer than that. If the feature is more complex than that, split it into smaller pieces and specify each separately.
  4. Write in whatever sequence makes the most sense to you as an author. We have found that the sequence that makes the most sense for reading a specification differs from that which makes the most sense for writing. This template is designed for readability at the expense of writability.

Enough meta-information. Time for real content:

What is the problem or set of problems we are trying to solve with this feature?

 

Functional Requirements

List what the application must do. This section is for the sole purpose of describing the problem to be solved by this feature. There are other sections below for proposed solutions to this problem and meeting all of the requirements, what the application will look like, what the window changes will be, etc.

 

New Terms and Definitions

This is the place to define new words and phrases to be used in the application and the documentation. If this feature introduces a new concept or changes the semantics of an existing concept in the application then define it here. Define it even if you think the definition should be obvious, since your definition might not match the definition used by the reader, like so:

    new term

    • new definition

    revised concept

    • new definition, followed by how the new semantics differ from the old

Related Existing Functionality

What does the application do now that is similar to the requested functionality?

 

Similar and Related Requests

What other requests have we gotten that might tie in nicely with this feature?

What open issues might be addressed by this feature?

Try to create hyperlinks to web-accessible data, such as this link to Mantis issue 2949.

 

Conflicting Features

What features currently exist and what feature requests have we received that might conflict with the feature described here?

 

User-Level Functionality

Describe how the new functionality will appear to and behave for the application user. To write this properly you will need to jump back and forth between this section and the Internal Design section.

Describe the menu changes and overall application structure changes here then get detailed in the subsections.

 

Window Changes

What windows do we expect to change?

What windows do we expect to eliminate?

What windows do we expect to add?

Insert screen shots of window mock-ups like this:

[Insert image here.]

Describe what each window does, what its fields mean, what the buttons do, what right-click menu items are available in the list views, etc.

 

Report Changes

What reports do we expect to create, eliminate, or change?

 

Batch Manager Changes

What functionality do we expect to add to, remove from, or change in the Batch Manager?

 

Usability Considerations

How do we think this will affect user access to existing functionality?

What problems do we anticipate users might have with this functionality and how can we minimize the impact of these problems?

What errors or abnormal situations do we expect users might encounter during normal processing and how can we make it easy for the user to fix these problems using the application?

 

Problems and Alternatives

What might go wrong with the solution described in this document?

Why might this not be the best solution?

What are the limitations of this approach? What's missing that might be desirable?

Describe briefly other ways to solve the basic problem and the advantages and disadvantages of each alternative.

Justify the chosen solution or argue why one of the alternatives would be better. Be as broad as possible here, since an important purpose of this section is to provide alternatives in case the initial attempt at implementation encounters a significant implementation block.

 

Internal Design

Now that we have defined what we have to do and how we think it should look to the user, we can describe the internal structure of the application. If possible, outline the architecture of the feature implementation here. Then in the sections below describe the changes and additions to the application to create this architecture.

 

Basic Algorithms

Are there particular algorithms required to implement this feature? If so, describe them here.

If you are going to outline a particular algorithm in pseudo-code
    put it in a programlisting
    try to limit lines to approximately 80 characters
    try to limit programming constructs while still being clear about intent
end if // a programming construct that may be unavoidable to maintain clarity

 

Custom Widget Changes

Do we expect to modify existing custom widgets to support the windows described above?

What new custom widgets will we need? Will they be derived from existing widgets? What behavior do we expect from them?

 

Schema Changes

What changes do we anticipate making to the database schema? New tables? Views? Indexes?

 

The new whatever-you-call-it table

Column Name

Description

Data Type

Comments

field1

Describe me

data_type

how it's used

foreign_key

Describe me

integer

foreign key to other_id

enum_field

Status or similar field

character(1)

Can take one of the following: 
* A value 
* Different Value 
* Final Value

 

What privileges do we need?

Privileges for feature

Name

Description

MaintainWhatever-you-call-it

Can Add/Edit/Delete stuff

ViewWhatever-you-call-it

Can View stuff

 

Stored Procedure Changes

What stored procedures do we expect to create, eliminate, or change?

 

Performance Considerations

How will this feature impact the performance of the application overall?

 

Error Handling

What internal errors do we anticipate might occur?

How can we best hide them from the user, prevent them, or fix them automatically?

 

QA Considerations

Does this feature require any special tools or data to test? Is it testable (some features may be hard to reach from the user level)?

What are some anticipated areas of concern that require special attention?

 

Documentation Considerations

Is there a significant documentation impact?

Does the feature require a standalone essay or only field-level descriptions?

 

Release Considerations

What release would we like to target?

What is the potential impact on a release if we don't finish in time?

What happens if we only get some of the functionality done?

Are there any pieces that would be useful on their own?

Are there any dependencies on other features or applications (such as Qt 4 or a particular release of OpenRPT)?

What is the anticipated impact on users, particularly those who have customized the sources, reports, and database schema?

 
ptyler's picture
Offline
Joined: 12/10/2008
Sample comment

This is a sample comment on the feature specification.

 
ptyler's picture
Offline
Joined: 12/10/2008
Another comment

This is another sample comment.