How to use this template:
- 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.
- Leave all headers in place. Simply insert N/A if the section does not apply.
- 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.
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?
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 definition
- 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.
What features currently exist and what feature requests have we received that might conflict with the feature described here?
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.
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.
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?
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.
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.
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?
What changes do we anticipate making to the database schema? New tables? Views? Indexes?
The new whatever-you-call-it table
how it's used
foreign key to other_id
Status or similar field
Can take one of the following:
What privileges do we need?
Privileges for feature
Can Add/Edit/Delete stuff
Can View stuff
Stored Procedure Changes
What stored procedures do we expect to create, eliminate, or change?
How will this feature impact the performance of the application overall?
What internal errors do we anticipate might occur?
How can we best hide them from the user, prevent them, or fix them automatically?
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?
Is there a significant documentation impact?
Does the feature require a standalone essay or only field-level descriptions?
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?