Difference between revisions of "Guidelines on writing Software specification"

From X-Cart 4 Classic
Jump to: navigation, search
(How to check whether your specification is accurate)
m
 
(12 intermediate revisions by 3 users not shown)
Line 18: Line 18:
 
'''Specific Functional Requirements'''
 
'''Specific Functional Requirements'''
  
* Are all the inputs to the system specified, including their source, accuracy, range of values, and frequency?
+
* Are all the inputs to the system specified, including their source, range of values and format?
* Are all the outputs from the system specified, including their destination, accuracy, range of values, frequency, and format?
+
* Are all the outputs from the system specified, including their destination, range of values and format?
 
* Are all output formats specified for web pages, reports, and so on?
 
* Are all output formats specified for web pages, reports, and so on?
* Are all the external hardware and software interfaces specified?
 
* Are all the external communication interfaces specified, including handshak-ing, error-checking, and communication protocols?
 
 
* Are all the tasks the user wants to perform specified?
 
* Are all the tasks the user wants to perform specified?
 
* Is the data used in each task and the data resulting from each task specified?
 
* Is the data used in each task and the data resulting from each task specified?
Line 45: Line 43:
 
* Where information isn't available before development begins, are the areas of incompleteness specified?
 
* Where information isn't available before development begins, are the areas of incompleteness specified?
 
* Are the requirements complete in the sense that if the product satisfies every requirement, it will be acceptable?
 
* Are the requirements complete in the sense that if the product satisfies every requirement, it will be acceptable?
* Are you comfortable with all the requirements? Have you eliminated requirements that are impossible to implement and included just to appease your customer or your boss?
+
* Are you comfortable with all the requirements? Have you eliminated requirements that are impossible to implement?
  
 
==Specification template==
 
==Specification template==
  
<pre>
+
<div style="border:solid 1px #A8A8A8; padding:0.5em 1em 0.5em 0.7em;  margin:0.5em 0em; font-size:85%; background-color:#F0F0F0">
1. Project summary
+
'''1. Project summary'''
  
This point includes project overview, scope and purpose. There should be brief list of new functions and necessary changes here.
+
This point includes the project overview, the scope and the purpose. It should present a brief list of the new functions and the necessary changes.
  
2. Terms and Definitions
+
'''2. Terms and Definitions'''
  
Optional point that describes all the new terms used in the specification and redefines already known ones.
+
Optional point that describes all the new terms used in the specification and redefines the already known ones.
  
3. Environment
+
'''3. Environment'''
  
Title and version of the sofware product to be modified (e.g. X-Cart Pro v4.3.1) and the direct URL to the software, if it is already installed (e.g. http://www.mysuperstore.com/xcart/).
+
Title and version of the software product to be modified (e.g. X-Cart Pro v4.3.1) and the direct URL to the software,
  
4. Functional requirements
+
if it is already installed (e.g. http://www.mysuperstore.com/xcart/).
 +
 
 +
'''4. Functional requirements'''
  
 
Roles:
 
Roles:
 +
* Store owner
 +
* Provider
 +
* Partner
 +
* Registered User
 +
* Visitor
  
- Store owner
+
'''USE CASE "[Title of first usecase]"'''
- Provider
 
- Partner
 
- Registered User
 
- Visitor
 
 
 
USE CASE "[Title of first usecase]"
 
  
 
[Description of first usecase]
 
[Description of first usecase]
  
USE CASE "[Title of second usecase]"
+
'''USE CASE "[Title of second usecase]"'''
  
 
[Description of second usecase]
 
[Description of second usecase]
  
USE CASE "[Title of third usecase]"
+
'''USE CASE "[Title of third usecase]"'''
  
 
[Description of third usecase]
 
[Description of third usecase]
Line 86: Line 85:
 
...
 
...
  
USE CASE "[Title of N-th usecase]"
+
'''USE CASE "[Title of N-th usecase]"'''
  
 
[Description of N-th usecase]
 
[Description of N-th usecase]
5. Other requirements (non-functional and system)
+
 
 +
'''5. Other requirements (non-functional and system)'''
  
 
This point includes requirements which impose constraints on the design or implementation (such as performance engineering requirements, quality standards, or design constraints).
 
This point includes requirements which impose constraints on the design or implementation (such as performance engineering requirements, quality standards, or design constraints).
  
6. Resources
+
'''6. Resources'''
  
 
Examples, links to documentation reference, sketches &etc go here.
 
Examples, links to documentation reference, sketches &etc go here.
  
</pre>
+
</div>
  
==Specification examples==
+
==Example 1. vBulletin integration==
  
1. vBulletin integration.
 
  
<pre>
+
<div style="border:solid 1px #A8A8A8; padding:0.5em 1em 0.5em 0.7em;  margin:0.5em 0em; font-size:85%; background-color:#F0F0F0">
 
+
'''1. Project summary'''
1. Project summary
 
  
 
Main scope of the project is to integrate X-Cart with vBulletin forum. Registration, profile updates and login functions should be merged.
 
Main scope of the project is to integrate X-Cart with vBulletin forum. Registration, profile updates and login functions should be merged.
  
2. Terms and Definitions
+
'''2. Terms and Definitions'''
  
 
There are no new terms and definitions.
 
There are no new terms and definitions.
  
3. Environment
+
'''3. Environment'''
  
 
New X-Cart v4.3.1. Not installed yet.
 
New X-Cart v4.3.1. Not installed yet.
  
4. Functional requirements
+
'''4. Functional requirements'''
  
 
Roles:
 
Roles:
 +
* Registered user
 +
* Visitor
  
- Registered user
+
'''USE CASE "User registration"'''
  
- Visitor
+
If a visitor registers in vBulletin, the system must create an account in X-Cart and fill it with the submitted data automatically. And vice versa, if a visitor registers
  
USE CASE "User registration"
+
in X-Cart, the system must automatically create a vBulleting account for him/her.
  
If a vistor registers in vBulletin, the sytem must create an account in X-Cart and fill it with the submitted data automatically. And vice versa, if a visitor registers in X-Cart,
+
If a field in one system does not have analogue in another, it will not be copied.
  
the system must automatically create a vBulleting account for him/her.
+
'''USE CASE "Personal information update"'''
  
If a field in one system does not have an analog in another, it will not be copied.
+
If a registered user updates the profile in vBulletin, his/her X-Cart profile must be updated as well. Same with X-Cart to vBulletin direction.
  
USE CASE "Personal information update"
+
If a field in one system does not have analogue in another, it will not be updated.
  
If a registered user updates his profile in vBulletin, his/her X-Cart profile must be updated as well. Same with X-Cart to vBulletin direction.
+
'''USE CASE "User logging in/out"'''
  
If a field in one system does not have an analog in another, it will not be updated.
+
Regardless of where a registered user submits his/her username and password, he/she must be logged both in vBulleting and X-Cart.
 
 
USE CASE "User logging in/out"
 
 
 
Regardless of where a registered user submits his/her username and password, he/she must be logged in both in vBulleting and X-Cart.
 
  
 
Regardless of where a registered and logged in user logs out, he/she is logged out in another system simultaneously.
 
Regardless of where a registered and logged in user logs out, he/she is logged out in another system simultaneously.
  
5. Other requirements (non-functional and system)
+
'''5. Other requirements (non-functional and system)'''
  
 
Changes must not slow down the entire system considerably.
 
Changes must not slow down the entire system considerably.
  
6. Resources
+
'''6. Resources'''
  
 
http://www.vbulletin.com/
 
http://www.vbulletin.com/
  
</pre>
+
</div>
 
 
2. Ability to register for providers
 
  
<pre>
+
==Example 2. Self-registry facility for providers==
  
1. Project summary
+
<div style="border:solid 1px #A8A8A8; padding:0.5em 1em 0.5em 0.7em;  margin:0.5em 0em; font-size:85%; background-color:#F0F0F0">
 +
'''1. Project summary'''
  
By default providers cannot register with X-Cart Pro. An administrator has to do it instead. The scope of the project is to add such ability. All the info should be submitted
+
By default providers cannot register with X-Cart Pro. An administrator has to do it instead. The scope of the project is to add such an ability. All the info
  
by a provider. And admin will just activate the account.
+
should be submitted by a provider and the admin will just activate the account.
  
2. Terms and Definitions
+
'''2. Terms and Definitions'''
  
 
n/a
 
n/a
  
3. Environment
+
'''3. Environment'''
  
 
X-Cart Pro v4.1.8 installed at http://www.yoursite.com/store/
 
X-Cart Pro v4.1.8 installed at http://www.yoursite.com/store/
  
4. Functional requirements
+
'''4. Functional requirements'''
  
 
Roles:
 
Roles:
 +
* admin
 +
* provider
 +
* visitor
  
- admin
+
'''USE CASE "New provider registration"'''
- provider
 
- visitor
 
 
 
USE CASE "New provider registration"
 
  
There must be a new registration form similar to the one for customers allowed at http://www.yoursite.com/store/provider/register.php
+
There must be a new registration form similar to the one for the customers allowed at http://www.yoursite.com/store/provider/register.php
It must contain all the fields an admin has to fill in while creating an account for a provider. When it is submitted, an email notification must be sent to an administrator.
+
It must contain all the fields an admin has to fill in while creating an account for a provider. When it is submitted, an email notification must be sent to the administrator.
Any visitor must have an ability to submit this new form. However the newly created account must be suspended until an admin approves it.
+
Any visitor must have an ability to submit this new form. However the newly created account must be suspended until the admin approves it.
  
USE CASE "Approval of new provider accounts"
+
'''USE CASE "Approval of new provider accounts"'''
  
There must be "Status" drop-down box at the provider profile modify page in the admin area. There must be two options: "Not acrive" (default) and "Active".
+
There must be a "Status" drop-down box at the provider profile modify page in the admin area. There must be two options: "Not active" (default) and "Active".
  
An admin must be able to change this property.
+
The admin must be able to change this property.
  
USE CASE "Provider log in"
+
'''USE CASE "Provider log in"'''
  
If a provider logs in, the system must check whether his profile is active or not. If it is not, an error message should appear instead of letting the person in.
+
If a provider logs in, the system must check whether his/her profile is active or not. If it is not, an error message should appear instead of letting the person in.
  
5. Other requirements (non-functional and system)
+
'''5. Other requirements (non-functional and system)'''
  
 
n/a
 
n/a
  
6. Resources
+
'''6. Resources'''
  
 
n/a
 
n/a
</pre>
+
</div>
  
 
==See also==
 
==See also==
  
 
* [http://en.wikipedia.org/wiki/Software_Requirements_Specification SRS on Wikipedia]
 
* [http://en.wikipedia.org/wiki/Software_Requirements_Specification SRS on Wikipedia]
 +
* [[Qualiteam professional services FAQ]]
 +
 +
[[Category:Qualiteam services]]

Latest revision as of 16:04, 11 May 2011

Introduction

A Software Requirements Specification (SRS) is a complete description of the behaviour of the system to be developed.

In our Customization Agreement it is mentioned as "Specification for Software Modifications" (or just Specification). It's the only place describing the changes to be made within a custom task. If something is not well-noted there, it's not taken into consideration while evaluating the task cost and therefore won't be implemented.

This article explains how to write a task specification saving your and our time. Remember, the more detailed you describe the desired changes the more quickly our project managers will estimate the task for you.

How to write a good specification

The best way to write a task specification is to complete our #Specification template.

How to check whether your specification is accurate

The requirements checklist contains a list of questions to ask yourself about your project's requirements. Not all of the checklist questions will apply to your project. If you're working on an informal project, you'll find some that you don't even need to think about. You'll find others that you need to think about but don't need to answer formally. If you're working on a large, formal project, however, you may need to consider every item.

Specific Functional Requirements

  • Are all the inputs to the system specified, including their source, range of values and format?
  • Are all the outputs from the system specified, including their destination, range of values and format?
  • Are all output formats specified for web pages, reports, and so on?
  • Are all the tasks the user wants to perform specified?
  • Is the data used in each task and the data resulting from each task specified?

Specific Non-Functional (Quality) Requirements

  • Is the expected response time, from the user's point of view, specified for all necessary operations?
  • Is the level of security specified?
  • Is the definition of success included? Of failure?

Requirements Quality

  • Are the requirements clear enough?
  • Does each requirement avoid conflicts with other requirements?
  • Are the requirements at a fairly consistent level of detail? Should any requirement be specified in more detail?
  • Should any requirement be specified in less detail?
  • Is each item relevant to the problem and its solution? Can each item be traced to its origin in the problem environment?
  • Is each requirement testable? Will it be possible for independent testing to determine whether each requirement has been satisfied?

Requirements Completeness

  • Where information isn't available before development begins, are the areas of incompleteness specified?
  • Are the requirements complete in the sense that if the product satisfies every requirement, it will be acceptable?
  • Are you comfortable with all the requirements? Have you eliminated requirements that are impossible to implement?

Specification template

1. Project summary

This point includes the project overview, the scope and the purpose. It should present a brief list of the new functions and the necessary changes.

2. Terms and Definitions

Optional point that describes all the new terms used in the specification and redefines the already known ones.

3. Environment

Title and version of the software product to be modified (e.g. X-Cart Pro v4.3.1) and the direct URL to the software,

if it is already installed (e.g. http://www.mysuperstore.com/xcart/).

4. Functional requirements

Roles:

  • Store owner
  • Provider
  • Partner
  • Registered User
  • Visitor

USE CASE "[Title of first usecase]"

[Description of first usecase]

USE CASE "[Title of second usecase]"

[Description of second usecase]

USE CASE "[Title of third usecase]"

[Description of third usecase]

...

USE CASE "[Title of N-th usecase]"

[Description of N-th usecase]

5. Other requirements (non-functional and system)

This point includes requirements which impose constraints on the design or implementation (such as performance engineering requirements, quality standards, or design constraints).

6. Resources

Examples, links to documentation reference, sketches &etc go here.

Example 1. vBulletin integration

1. Project summary

Main scope of the project is to integrate X-Cart with vBulletin forum. Registration, profile updates and login functions should be merged.

2. Terms and Definitions

There are no new terms and definitions.

3. Environment

New X-Cart v4.3.1. Not installed yet.

4. Functional requirements

Roles:

  • Registered user
  • Visitor

USE CASE "User registration"

If a visitor registers in vBulletin, the system must create an account in X-Cart and fill it with the submitted data automatically. And vice versa, if a visitor registers

in X-Cart, the system must automatically create a vBulleting account for him/her.

If a field in one system does not have analogue in another, it will not be copied.

USE CASE "Personal information update"

If a registered user updates the profile in vBulletin, his/her X-Cart profile must be updated as well. Same with X-Cart to vBulletin direction.

If a field in one system does not have analogue in another, it will not be updated.

USE CASE "User logging in/out"

Regardless of where a registered user submits his/her username and password, he/she must be logged both in vBulleting and X-Cart.

Regardless of where a registered and logged in user logs out, he/she is logged out in another system simultaneously.

5. Other requirements (non-functional and system)

Changes must not slow down the entire system considerably.

6. Resources

http://www.vbulletin.com/

Example 2. Self-registry facility for providers

1. Project summary

By default providers cannot register with X-Cart Pro. An administrator has to do it instead. The scope of the project is to add such an ability. All the info

should be submitted by a provider and the admin will just activate the account.

2. Terms and Definitions

n/a

3. Environment

X-Cart Pro v4.1.8 installed at http://www.yoursite.com/store/

4. Functional requirements

Roles:

  • admin
  • provider
  • visitor

USE CASE "New provider registration"

There must be a new registration form similar to the one for the customers allowed at http://www.yoursite.com/store/provider/register.php It must contain all the fields an admin has to fill in while creating an account for a provider. When it is submitted, an email notification must be sent to the administrator. Any visitor must have an ability to submit this new form. However the newly created account must be suspended until the admin approves it.

USE CASE "Approval of new provider accounts"

There must be a "Status" drop-down box at the provider profile modify page in the admin area. There must be two options: "Not active" (default) and "Active".

The admin must be able to change this property.

USE CASE "Provider log in"

If a provider logs in, the system must check whether his/her profile is active or not. If it is not, an error message should appear instead of letting the person in.

5. Other requirements (non-functional and system)

n/a

6. Resources

n/a

See also