Hi bert1-ga,
Your query is one that has been asked time and time again by software
developers. Luckily, standards have been defined that outline how to
proceed with the development of non-trivial applications. First, let's
consider the high-level stages of the SDLC (Software Development Life
Cycle):
"User Requirements definition
Software Requirements definition
Architectural Design
Detailed Design and construction
Delivery to the user
Operations"
http://ipt.web.cern.ch/IPT/Papers/Sopron94/CSCproceedings_10.html#HEADING9
At each stage of the SDLC, emphasis is placed on the creation and
modification of supporting documentation. Some common types of
documentation include:
"User Manuals
Reference Manuals
Design Documents and Technical Specifications
Software Life-Cycle Reports
Customer reports
Maintenance Reports
Testing Reports
Usage Reports
etc."
http://www.cee.hw.ac.uk/~ph/docs1.pdf
Since your question deals with outlining specifications, the
document(s) you need to compose fall under the "Design Documents and
Technical Specifications" group. The most effective method of clearly
laying out the various functions and interdependencies of a software
application is by employing the use case methodology. Several
Question/Answer pairs are laid out below to give you an idea of this
concept:
What is a Use Case?
"A Use Case (also called a scenario) captures a contract between the
stakeholders of a software system about its behavior. Use Cases
describe the software system’s behavior under various conditions as it
responds to requests by the users. Essentially, it provides an
easy-to-understand representation of the functional requirements for a
software system."
Why are Use Cases an effective means of requirements gathering?
"• They officially document the development process
• They can separate the functional requirements from the business
process
• They serve as requirements documentation for software development
• They are easy-to-read and easy-to-understand
• They can be used to categorize and rank requirements
• They can identify possible system/component reuse"
Due to these benefits, Use Cases are now becoming customary as a
method for gathering requirements.
The answers to the above questions were adapted from an academic
research paper, which I suggest you read closely for a full
understanding of use cases. The appendix also includes a sample layout
of a use case (though additional formatting could be added):
http://www.bus.iastate.edu/nilakant/MIS538/Readings/Gather%20Req%20UC.pdf
Each use case follows a consistent format - this is one that I have
found useful yet concise:
Actor (who can perform this function?)
Precondition (what must occur before this function can be accessed?)
Postcondition (what will happen once the function is complete?)
Trigger (how does the system know when to perform this function?)
Assumptions
Main Scenario (includes what actor does and how system responds)
1. Step 1
2. Step 2
3. Step 3
4. Step 4
Alternate Scenario(s) (potential paths that could occur depending on
input)
Exceptions (possible ways the use case will not complete in a
main/alternate scenerio fashion; for example, the actor decides half
way through that they do not want to perform the function)
Owner: (creator of use case)
A single document is then created, typically called a requirements
document, which includes all use cases along with some additional
housekeeping information. Below is a format that I personally use to
lay out this document (along with a brief description of each
section):
TABLE OF CONTENTS
DOCUMENT CONTROL
DOCUMENT LOCATION - where is "master" copy located?
ACCEPTANCE - is this an external document that must be accepted by
sponsor?
REVIEW DISTRIBUTION - who has received the document for review?
REVISION HISTORY - table of date, author, description of changes
1. EXECUTIVE SUMMARY - overview of the project's purpose and benefit
2. INTRODUCTION
2.1. DOCUMENT SCOPE - limits what application(s) is/are being
considered
2.2. GLOSSARY - terminology used in document and meaning of each
3. GENERAL AND NON-FUNCTIONAL REQUIREMENTS
3.1. GENERAL REQUIREMENTS - high-level; could be groups of use cases
3.2. NON-FUNCTIONAL REQUIREMENTS - cannot be described as a function
(ie. performance, ease of use, availability etc.)
4. SPECIFIC REQUIREMENTS
4.1. DESCRIPTION OF ACTORS - what is an actor; list and description of
actors in this system
4.2. OVERVIEW OF USE CASES - listing and brief description of each use
case
4.3. USE CASES
4.3.x. INPUT USE CASE x HERE
5. APPENDIX A – USE CASE PRIORITY AND EFFORT TABLE -
listing/description of the main scenario and all alternative scenarios
for each use case
6. APPENDIX B – SUMMARY OF FUTURE REQUIREMENTS - possible future
additions to the application that has not yet been considered
Although use cases are very useful in preparing the types of
specifications you are looking for, it is useful (from my own personal
experience) to also develop a test plan in parallel. A test plan is
composed of a group of test cases, each of which correspond to one use
case and lays out, in detail, how the successful development of a
particular function should be verified. If necessary, test data should
also be included with the test case for the tester(s) to use. This
ensures that any variations in data entered are considered.
The format for each individual test case is as follows:
Name of the test (possible with a number for easy identification)
Overview of the purpose of the test
Equipment needed for the test
Description of test setup
Description of any additional hardware needed
Description of dummy software front ends needed
Description of data collection software needed
Specific description of the inputs to be used in the test
(Include specific "end point" data to be tested)
Description of expected result for all data points tested
(Include precision needed for numerical data)
After you have completed your tests, you should add the following
sections to each test case (leave these sections empty for now):
"Test log and results Date and time test was performed
Engineers involved in the test
Any differences between the planned test and the actual test performed
Table of measured data, if applicable
Observations during test, if no numerical data taken
Comments on test
Overall result of test (Complete Pass/Partial Pass/Fail) and
description of what did and didn't work.
Signatures of all involved in the test."
http://myhome.spu.edu/bolding/EE4211/design_notebook/test_plan.html
Once all individual test cases have been designed, they can be
collected and placed into a single document called a test plan. The
outline of the test plan is as follows:
1. TABLE OF CONTENTS
2. DOCUMENT CONTROL
2.1. REVISION HISTORY - who/when/what for changes made
3. PROJECT OVERVIEW - description of the contents of the document
4. PURPOSE - what should be achieve with each test case
5. TEST MATRIX
5.1. FUNCTIONAL REQUIREMENTS MATRIX - ensures that each use case is
tested at least once
5.2. STRUCTURAL REQUIREMENTS MATRIX - repeat info from general
requirements in requirements document
5.3. TEST REQUIREMENTS COVERAGE MATRIX - alignment of test cases with
use cases
6. TEST CASES
6.x. TEST CASE x - insert test case here (corresponding order with use
cases)
7. TEST DATA
7.x. DATA FOR CASE x - data required as input for test case x
You will have noticed that I have not talked about DDE or OLE in this
discussion, and the reason for this is that requirement definition
doesn't depend on which technology you employ to solve your problem.
These documents are designed to provide a generic solution for ALL
types of software projects and are useful in both technological and
business environments.
I hope you have found the above helpful in resolving your dilemma - if
you have any problems understanding the information above please do
feel free to post a clarification and I will respond promptly :)
Cheers!
answerguru-ga |
Clarification of Answer by
answerguru-ga
on
27 Dec 2002 01:01 PST
Bert,
I definitely see your point, and it is reasonable to expect that
components be reused wherever appropriate. While documents along the
lines of those outlined in my original response have become somewhat
of an industry standard, there is nothing forcing a given firm to
conform to that structure. With any best practices type material,
customizations should be made to better suit the environment.
It is strongly suggested that you include the information previously
outlined as part of your own specification document, as that builds
the basis of understanding for your staff so that they can see the
component-wise purpose of the project as a whole. There are a few
different ways that you can clarify your expectations to your software
personnel:
MEETINGS/MEMORANDUMS
This is the obvious option, but it works if you do it correctly. This
will require you to sit down and work through all of the use cases of
the program being developed to obtain a reference that marks your
objectives. A common trap that developers fall into is getting into
the "how" of problems without first clearly defining the "what". You
may be surprised to find that some of the components you have slotted
for use in certain places may not fit as well as you originally
thought. But of course if you have laid everything out and the pieces
of the puzzle come together then that's great! This is a form of
verification prior to actually developing anything, which saves a
serious amount of time and resources.
Now for the meeting preparation; its unlikely that your developers
will have time to read through the lengthy document you've created
unless they are directly responsible for a given use case, so you need
some visual aids and simplified documents to help make your
point...you've already done the work for this, its just a matter of
pulling the pertinent information out of your document.
The meeting itself should be interactive with the purpose of "proving"
your vision and getting everyone on board.
SPECIFICATION MODIFICATION
The other option is to actually build in a specified set of
ready-to-use components into an appendix as a resource group that is
available. Reference should also be made to the documentation for
these components so that your developers who are unfamiliar with them
can find and plug in the pieces where appropriate. Going one step even
further, you could add an extra section into each use case which
specifies a set of ready-made components that *may* pertain to that
case in particular. You may want to express this as a table that
includes each component as an entry that includes other relevant
information (such as component owner/developer, compatibility, etc.).
For a developer, what this will do is introduce the "what" of the
function in detail, and then a suggestion for the *how* in terms of
the components already available to them. This will guide them to
frame the problem with the components as the tools available to
them...keep in mind that this may be detrimental to the development
process if this information is misleading or inaccurate, so check it
twice!
Hope that clears things up :)
Cheers!
answerguru-ga
|
