Technical writing/Requirements EE

Back to Writing Requirements and Functional Specifications(EE)

Requirements are essential for systems and software

Availability is the percentage of time that the system must operate without failure

Example A telephone exchange must operate 99.9997% of the time. 100% Availability is unachievable)

A Functional Requirement describes the functions a system must perform.

A Non-functional requirement is how well the system performs the functions. These are, among others:

• performance requirements
• quality of service requirements

Examples of such requirements include

• The Availability of the system
• How easy the system is to
  • Test
  • Maintain
  • Use

Requirements define the characteristics or features of the system.

Well written list of requirements do not say how the system should implement the requirements

How the system implements the requirements is the job of the system designer.

Requirement Specification Topics

Most requirements specifications include the following nine topics.

The first three describe Functional Requirements:

• Interfaces
• Functional Capabilities
• Data Structures/Elements

The last six topics address quality requirements and are considered non-functional:

• Performance Levels
• Safety
• Reliability
• Security/Privacy
• Quality
• Constraints & limitations

Remember the following when writing requirements:

• The requirement specification is to express requirements, not an outline for a method to derive the requirements.
• Use proper sentence structures and select words and phrases based on their formal definitions
• Write simple direct statements. Follow a disciplined and iterative approach to create the requirement specification.

Exercise 2 Make a label for a bottle of Beer with known requirements

The exercise aim is to show how dangerous it is to assume you know what your Customer needs.

Your Customer then tells you the Requirements.

1. Pilgrim is a non alcoholic beer that complies with Islamic law.
2. No representational art is allowed on the label.
3. Pilgrim is also Halal

NOTE: If you assume then you make an ASS out of U and ME. (An Ass is a donkey)

The Software(Systems)Development Life Cycle

The process for developing software and systems is called the SDLC, Software (or) System Development Life Cycle

Requirements are written in the first third of the Concept phase of life cycle, modified and tracked in the constructing phase, and used as testing and acceptance criteria in the constructing and Using phases. In addition, they provide the basis of user documentation and training, as well as the library of lessons learned for the next project.

How does the team transform an idea into a tool that people can use?

The process in steps

The Concept

• Initialization
• Analysis and Planning

Constructing the concept

• Design
• Development
• Testing and Integration

Using the concept

• Delivery
• Maintenance
• Improvement

Example 1 Construct an office building

The process is as follows:

The Concept

• the Initialization of the project.

1. • Discover the Goals
     • A one floor office suitable for a call centre with 50 workers
     • Close to the centre of town
2. analyse feasibility of the concept
   • Is there a Market for extra office space?
   • Will the local Municipality grant permission for the building?
   • Is there enough money to complete the project?
   • Is there enough room on the building site?
   • Will there be access by road?

Constructing the Concept

1. plan the building.
   • Requirements. There must be:
     • Enough space for Call Centre 50 workers plus support workers
     • Cleaning
     • Reception
     • Parking
2. design the building
   • does the design of the building satisfy all the above Requirements and all the safety Requirements?
3. Construct the building with proper tools
4. Integrate by connecting the building to the road system, electricity, water, gas, telephone,internet, waste water
5. Test the building
   • Does the building satisfy all the above Requirements?
   • Does the building satisfy all the safety Requirements?

Using the concept

1. Delivery of the building open the building to the occupants with all relevant documentation
2. Maintenance of the building
3. Analyse the knowledge gained from constructing the building and construct a better building next time

Exercise 3 Paint a picture

The exercise aim is to

1. conceive an image
2. sketch the image
3. modify the image
4. design the image
5. paint the image on the canvas (use correct the tools)
6. frame the finished picture
7. take the picture to a gallery
8. analyse the knowledge gained from painting the picture and paint a better picture next time

Writing Clear Requirements

Use imperatives to write requirements.

Imperatives (grammatical term) are direct commands

Example "eat your food"

Strong Commands Shall, Must, Will

Strong Prohibitions Must not, Cannot, May not, Shall not, Must Never.

Weak Suggestions Can, May, Alternatively , if possible.

Useless General terms Should, Big, Small, Easy, Friendly.

Remember use the strongest imperatives available.

General (non specific) terms must not appear in a requirement specification.

If the requirement cannot be measured or tested then restate the requirement and use strong language.

Using Commands

Deliverables are the product features that will appear in a contract.

Commands are a direct order.

Example "Eat all your food."

Note: The second person (you) is always implied Commands are imperative. Commands are strong and define:

• what the developers must make
• how to test that the function works

Testing the commands against the Deliverables is how Customers check whether they have received what they paid for.

Strong commands follow a pattern:

• Commands are short
• Commands use active voice
• Commands use strong verbs
• Use these verbs:
  • Shall
  • Must

The strongest verbs are Shall and Must. Shall and Must leave no doubt that what follows is a necessary. The word Will is reserved for a statement of fact.

Using Prohibitions

In safety warnings, negative prohibitions are necessary in requirements. Often the prohibitions will reflect safety and environmental concerns.

Strong Prohibitions:

• Shall not
• Must not
• Cannot
• May not
• Do not
• Never

Note: In the command form, Can and May are weak, but used as a prohibition, Cannot and May not are strong.

• Never put needles in your ears.

• The system must not allow users to delete files.

Requests

Requests must not appear in a strong requirement specification. Suggestions and requests will probably be ignored or badly implemented.

Never use:

• Should
• May
• Can
• possibly

Examples of suggestions

• The parachute should open when you pull the ripcord
• We should all live in peace and harmony with nature.
• The system should store user information without loss of data.

The above are all nice ideas and wonderful concepts.

We all agree with the suggestions.

But realistically, they are just nice suggestions not requirements.

So avoid any kind of ambiguous request.

General terms do not specify

General terms do no supply enough information

• How tall is high?
• How little is small?
• How big is large?
• How much is enough?
• How Quick is quickly?

If the requirements include terms that can be misunderstood then these terms that will require further explanation.

Do not use General terms.

Replace with General terms with specific measurable requirements.

How to convert a General term into a specification

Examples:

Too general: Enough memory for the users.

Specific: The system must provide 20 GB of free hard drive space for each user.

Too general: The system shall shut down quickly.

Specific: The complete power down sequence shall last no more than five (5) seconds.

Requirements

A Requirement is a single piece of information about what a product or service does or is. Developing engineers use Requirements. The Requirement identifies a necessary attribute, capability, characteristic or quality that must be of use to the person using the product.

Requirements show that the elements and function are necessary for the particular project.

Requirements are typically placed into these categories:

Functional requirements describe the functions that the system must execute; Non-functional requirements constrain the solution. Nonfunctional requirements are sometimes known as constraints or quality requirements. They can denote something about the system itself, and how well it performs its functions. Examples of such requirements include availability, testability, maintainability, and ease-of-use.

Often 'business need' and 'feature' are spoken of as types of requirements. Each functional requirement should be traceable up to system feature and business need. The requirements phase may be broken down into three phases: elicitation (from the end user), analysis (with the end user) and recording:

• Elicit – the developer must obtain the end user’s requirements for the project by asking questions and drawing out every detail.
• Analyse – the requirements must be evaluated for accuracy, completeness and deliverability by discussion between the developer and the end user.
• Record – the requirements must be recorded flexibly, leaving room for additions and revisions. Use an open numbering/ID system for this.

Characteristics of good requirements

Good requirements should include statements that are:

• Necessary – Something that must be included.
• Unambiguous – Use strong words without vague terms.
• Concise – Easy to read yet conveys the essence of what is required.
• Consistent – Does not contradict other requirements. Contains a terminology list for key words.
• Complete –Does not require you to look at additional text to know what the requirement means.
• Achievable – A realistic requirement that can be implemented with the available money, resources, and time.
• Testable – Can be tested by inspection, analysis, or demonstration.
• Traceable - Has a unique identifier and is tracked through the entire SDLC.

The Requirements must contain all the required features

Requirement specifications must contain all required features, none must be left unrecorded. If it is difficult to define expected system action/output in some conditions, such issues should be recorded and clarified/defined later when it becomes possible. "Common sense" requirements sometimes are left unrecorded by analysts/developers. However, remember that "common sense" is an ambiguous characteristic. Record all requirements which are necessary even if you think they are "common sense".

Your requirements specification document must have a clear structure. It must be easy to find any information, navigate within the document. You should avoid referencing a reader back and forth within the document. If your reader must hold fingers on more than 2 pages when reading any requirement, consider re-writing it.

The requirements specification is a project deliverable whether or not it is required by a customer. Like any project deliverable, it must be tested. Ask your colleagues to review it. It's a good practice to have software architects, test engineers, and customers review your specifications and provide feedback.

Requirements Writing Summary

Use Strong Words and Phrases

• Use the simplest words appropriate to the intent of the statement.
• Use imperatives correctly and be consistent. Remember, shall "prescribes", will "describes", must & must not "constrain", and should "suggests"
• Avoid weak phrases such as "at a minimum", "be able to", "capable of", and "not limited to".
• Do not use words or terms that give the provider an option on the extent that the requirement is to be satisfied such as "may", "if required", "as appropriate", or "if practical".
• Do not use generalities where numbers are really required such as "large", "rapid", "many", "timely", "most", or "close".
• Avoid fuzzy words that have relative meanings such as "easy", "normal", "adequate", or "effective"

Provide Examples

• Immediately follow what is to be illustrated with the example.
• Repeat an example if it is not already located on the same page. Its better to be repetitive than to divert the reader's attention.

• Ensure that the example is not mistaken as part of the specification by the use of italics, quotes, or being explicit. For example: "This is an example."

Cite References

If the industry standards that apply to the project are too long to include in the document the site the original document as a reference.

Identify each reference cited with a unique number or identifier, such as "2.14". Cite references by:

• short or common title
• full title
• version or release designator
• date
• publisher or source
• document number or other unique document identifier.

For example: "2.14 NASA Software Management, Assurance, and Engineering Policy, NMI 2410.10, March 26, 1991."

Use the same unique citation identifier when referencing information in the cited document. For example: " as defined by Section 3 of reference document 2.14."

Use Tables and Charts

• Each table must have a unique Title and an Identify
• List each table and chart in the Requirements Specification's table of contents by title, unique identifier and page number. Help the reader find it!
• Identify the purpose of the table or chart in the text immediately preceding it.
• Explain each aspect or element of the table or chart (columns, rows, symbols, blanks, etc.) from right to left then top to bottom

Use Careful Word Order in English

The general form of a requirement is. "who will do what where when followed by constraints".

The Requirements do not state how the system performs the functions required. The System Architect decides how to implement the functions. Requirements should be prioritized, allowing more effective management (e.g. release planning, change control), and also carefully structured so that relationships are made clear.

According to NASA each specification statement consists of four basic structural elements:

• Entities
• Actions
• Events
• Conditions

These elements can be used or modified by various cases such as:

• Owner
• Actor
• Target
• Constraint
• Owned
• Action
• Object
• Localization

The recommended model for a specification's structure is: [Localization] [Actor|Owner] [Action] [Target|Owned] [Constraint]

In this example: "The pizza boy will deliver the pizza to Fred's doorway no later than 13:30 GMT on 23 September, 2027, unless Fred doesn't pay." Localization: "Fred's doorway" Actor|Owner: "pizza boy" Action: "deliver pizza" Target|Owned: "pizza" Constraint: "Fred doesn't pay"

 

Keep it short

• All your commands and prohibitions must be short.
• Break long sentences and paragraphs into short commands and lists.
• Use the active voice and present tense.
• If a sentence has more than 3 punctuation marks, re-write it to make easier to understand.

Use consistent terminology

• Define all technical terms in a glossary or terminology database so there is no disagreement on meaning.
• Don't use synonyms. Always use the same term for the same meaning.

Break long sentences

• Chunk the information to the level developers will understand.
• Sort the chunks into comprehensible groups using tables and lists.
• A sentence with many commas, or words like or, and, but, and/or, contains lumps of requirements. It must be broken down further.

Remember the reader

• Target your writing to your reader.
• Developers want exact, clear, organized prose with testable statements.
• Testers want enough information to infer the test cases, but you don't have to write every possibility.
• Avoid redundancy. State it once and then make references to that statement.

Testable requirements

Requirements must be testable.

If the requirement is difficult to test then use one of the following verification methods instead:

• analysis
• inspection
• designe review

Certain requirements are not testable within a reasonable time limit.

Requirements that state that the system shall not fail for 25 years would take 25 years or more to test. It is better to state a Mean Time Between Failures (MTBF) which can be calculated by a mathematical formula. Such requirements are often rewritten to state a more practical time period.

Example of a simple requirement

A simple requirement could be:

Requirement ID Requirement Description UR-040 Only authorized users can access the database

Each requirement leads to one or more test cases:

Requirement ID Requirement Description Test Cases UR-040 Only authorized users can access the database Attempt to log in with an UserID not in the authorized user database Attempt to log in with a correct UserID and incorrect user password Attempt to log in from outside the firewall

Every time you write a requirement, you must ask yourself if it is testable. This means a tester must be able to prove the statement false. If it is not possible to prove the statement false, then you must restate the requirement.

Traceable requirements

With time, requirements will usually change - Customers change their minds. The market changes and demands additional requirements. Developers find new solutions that impact on the rest of the system. Attempting to set the requirements in stone is impossible. Instead, you define the requirements as clearly as you can, and anticipate they will evolve over the life cycle of the project. By assigning a unique identifier to every requirement, you can control this inevitable process.

Unique Identifiers and Tracking Changes

There are many ways to label and number requirements. Allow for the system to expand, use whatever is reasonable for your audience. For example, to create requirements for a pocket calculator the following types of requirements are necessary:

• Size
• Mathematics Functions
• User Interface
• Power

Each of these types of requirements contains many sub-requirements, so you can put them into a table:

Calculator Size Requirements (1st draft) S-010 The calculator must be no wider than 10 centimetres. S-020 The calculator must be no longer than 15 centimetres.

Over time, though, you discover new requirements and add them to the end of the list. Where it makes sense, you can also add requirements in the middle of your list:

Calculator Size Requirements (with new items)

S-010 The calculator must be no wider than 10 centimetres. S-011 The calculator must be no wider than 12 centimetres at the bottom. S-020 The calculator must be no longer than 15 centimetres. S-030 The calculator must be no heavier than 20 grams. S-031 The calculator when containing batteries must be no heavier than 30 grams.

Construct the Unique Identifiers so that more items can be added. In the example from a previous page, each Unique ID has an interval of ten so nine additional requirements can be inserted anywhere in the list. Of course you can also add items to the end of the list. Remember: DO NOT re-number Unique Identifiers. Once an item has an identifier, don't change it. (For this reason do not use the word processor's auto-numbering tools.)

Requirement Evaluation Check-list

A Requirement Specification is an iterative document that records the plans and intentions of the development team. As those plans and intentions change, then the specifications must change.

Ask these Questions every time there is a new requirement or a requirement is modified.

1. Does the requirement state what is required rather than a solution?
2. Is the requirement easy to understand and difficult to misunderstand?
3. Does the requirement contain simple short statements with only one possible meaning (easy to understand and difficult to misunderstand)?
4. Is there an example that explains the requirement? Is an example needed?
5. Is there a diagram that illustrates the requirement? Is a diagram needed?
6. Does the requirement contradict any other requirement?
7. Is the requirement complete? (if the reader must search for information to understand the requirement then the requirement is not complete)
8. Is the requirement uniquely identified?
9. Can the requirement be tested?
10. Can the requirement be traced to and from a business objective?
11. Can the requirement be achieved with the given resources, time and technology?

There is a suggested check-list available for download and use at SSC San Diego Process Asset Library http://sepo.spawar.navy.mil/SPIWG/SPIWG_RD_Writing_Requirements.doc. You can also try NASA's Automated Requirements Measurement (http://satc.gsfc.nasa.gov/tools/arm/) tool which is free for download and use.

Since the typical requirements specification has multiple authors, you'll find yourself editing what others have written. Similarly, you'll find others editing your words. This must be expected and encouraged.

At each phase the writers, managers, developers, architects, and the customers, must challenge and define the requirements. As this process continues, the requirements become better understood. Out of scope requirements are identified and eliminated. All the stakeholders set priorities, so managers can break the work into phases. The design becomes clear, and only when the most important issues have all been answered should you begin the actual development phase.

Definitions

A Requirement is: A well defined description of what a single aspect of a particular product or service must be or do. The description is an input to the design stage of product development.

A Functional Requirement describes the Functions a system must perform.

An MTBF is the Mean time between failures and is calculated mathematically by taking account of all the components that coulkd fail

A Non-functional requirement is how well the system performs the functions.

A Customer is: a person or organisation with goals that pays for the project

Imperatives are direct commands, requests, and prohibitions.

'Example “be quiet”

• Back to Writing Requirements and Functional Specifications(EE)
• Back to Technical Writing Level 1
• on to The Roles of the Development Team (EE)