Technical writing/Specification

This Requirements Writing Workshop is part of the Technical Writing School at Wikiversity Defining accurate user requirements is the basis of successful software development. Yes, it's open source learning. Edit this page! Your instructor is TWFred Part of Technical Writing at Wikiversity Wikipedia definition of Requirements Wikipedia definition of Specification Send TWFred an Email. Part of the Engineering and Technology Wikiversity Portal Our Wikiversity Learning Experience so far... How to edit Wiki Wikiversity Main Page

Leading the Systems Development Lifecycle Congratulations. You've got the job of leading a development team. Now what? Well, chances are that you grew up reading science fiction, dreaming of exploring and creating new worlds. Here's your chance to turn that dream into reality. Defining system requirements is creating the future. Writing requirements is describing the future as accurately as possible, so it can then be produced by designers and developers. Doing this properly takes considerable time and effort. The top fivecriteria for project success are: User Involvement Executive Management Support Clear Statement of Requirements Proper Planning Realistic Expectations Although we've known this for years, we still jump into projects without defining the requirements first. In a way, it's like writing science fiction. You'll use the future tense to describe in a concrete way just what must be created. Then you'll use the present tense to test whether those functions and structures work. This workshop provides you with a practical way to describe functional and structural requirements for systems development. Read more about project management strategy.

Navigation

Requirements Evaluation Check-list

A requirements specification is never really done. It is an iterative document that reflects the plans and intentions of the development team. As those change, so must the specification change. It's a living record of what you are doing.

Still, you can check the quality of your communications. At every stage as you add, edit, or remove information ask yourself these kinds of questions:

1. Does the requirement focus on 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, unambiguous statements?
4. Is there an example illustrating the requirement? Is it needed?
5. Is there a visual figure illustrating the requirement? Is it needed?
6. Does the requirement contradict with any other requirement?
7. Is the requirement complete (without requiring a reader to look for information elsewhere to understand the requirement)?
8. Is each 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. You can also try NASA's Automated Requirements Measurement 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, there should be a healthy back-and-forth between writers, managers, developers, architects, and the customers, each challenging and defining 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.

"But we don't have time for requirements...."

If you try to build a house with no plans, just stacking bricks and hammering wood together, you're unlikely to succeed. Everyone knows you need plans first.

Some people begin coding before they understand the requirements. It's no wonder their software, like a house with no plans, crashes down.

How much time?

Experienced professionals spend between a quarter and a third of their time and effort on defining the requirements, planning, and design.

Incorrect from the instructor: Highly successful projects write test cases before they write code.

Corrected by Technical Writer: Highly successful projects include written test cases prior to coding.

Similarly, delivery, maintenance, and improvement of the software must be included in project planning from the beginning. When these crucial activities are left as an afterthought, the customer is rarely satisfied.

A rough guideline for successful projects:

• 1/3 project initiation, analysis, planning, specification, design, user feedback

• 1/3 development, testing, integration, documentation, user feedback

• 1/3 delivery, training, maintenance, user feedback, improvement

Note: All projects vary, but those which short change the first third of the process to jump directly into development are at highest risk for failure no matter the size or complexity of the project.

Avoid this risk by focusing on user goals. Keep your users involved through the whole life cycle of your project.

It takes time and skill to do this work. It's not for junior personnel, since this type of work affects the fortunes of the whole company. Experienced business analysts, writers, designers, architects, and managers can spot problem areas. If there is ever a time to put your best people on the job, it's during the requirements analysis and design phases.

Focus on Meeting User Goals

User Goals, Functions, and Structures The Cycle of Goals, Functions, Structures User Goals Driven System Development Life Cycle Clarify and define User Goals, within their environment User Goals within environmental constraints are prioritized as Requirements Discover and describe Functions that meet the Requirements Detailed Specification of the Functions and user environment is the design for Structures Structures produce a Product Compare the Product against the User Goals Repeat the lifecycle... Small and frequent repetitions of this life cycle allow you to grow the system organically, building on previous successes and constantly ensuring that user goals are met. Communicate with the Users Look again at the major risk factors for all projects. The number one reason projects succeed or fail is user involvement. It's a mistake to think of requirements specification as something you check off your list before starting the "real work". Teams that diligently gather requirements, then hide in the office to create the product (or worse, a prototype) will not be as successful at managing and meeting the user's expectations. All the way through the development lifecycle, from initiation, through development, to improvement, you must keep close to your customers and welcome their involvement in mutually evolving the product to meet their goals.

The Development Life Cycle

How is an idea transformed into a tool that people can use?

It doesn't happen automatically. It takes people working together, pooling their specialist knowledge, sharing problems and solutions until they have reached their goals and introduce it to the world.

This development process repeats in so many areas of life. To build an office tower, first you have to have the idea, analyse and plan it, design it, actually build it with proper tools, open it to occupants, and maintain it. You think of what you have learned in building this structure, and how to do better next time. Stretching the analogy further, to paint you have to conceive an image, sketch, modify and design it, then paint it on the canvas (again, with the proper tools of course), frame and present it to a gallery, and follow it over its lifetime. You brood over the paintings you have created, planning how to improve your style.

In just about any endeavor where you build things, you'll find the same phases:

The Idea

1. Initialization
2. Analysis and Planning

Building the Idea

1. Design
2. Development
3. Testing and Integration

Using the Idea

1. Delivery
2. Maintenance
3. Improvement

In building software and systems, it's called the SDLC, Software (or) System Development Life Cycle.

Some formal methodologies have more or fewer "phases" or "steps" in their life cycles, but they all follow this same pattern.

Note from Technical Writer: Remove personification - "they"

Requirements are written in the first third of the Idea phase of life cycle, modified and tracked in the Building phase, and used as testing and acceptance criteria in the Building 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.

Note from Technical Writer: Remove personification - "they"

The requirements are not separate from the design, tests, or user documentation. The requirements are the roots of all these other documents. Therefore it makes sense to keep requirements open, visible, and in constant flux.

Note from Technical Writer: Remove personification - "they"

The more they change and the more your users, developers, testers, and managers use them, the more likely you'll have a successful project.

The specific methodology you use is less important than simply reaching clear written agreement reflecting understanding between the developers and users.

Requirement Specification Patterns

There are hundreds of templates and dozens of methodologies each requiring more or less the same basic areas for specification.

1. Functional Specifications tracked to User Goals
2. Workflows and Dataflows
3. User and System Environment Constraints & Limitations
4. Data Structures, Elements, Interfaces, Inputs, Outputs
5. Performance, Safety and Reliability
6. Security/Privacy

The closer you understand your user goals, the more naturally you will tailor your requirements to your project.

Quality Red Flags

There are some red flags you should always watch out for:

• Generalizations like "user friendly", "fast", or "24/7"
• No description of inputs or outputs
• Lots of long paragraphs
• Structures without a clear link to functions and user goals

Get it in Writing

Requirements Writing in Four Steps A requirement is a singular well-defined description of what a particular product or service must be or do. Sets of requirements are used as inputs into the design stages of product development. Your job is to clarify the user goals and convert them into separate testable statements. Business analysts often use the following iterative steps: elicitation (gathering the requirements from stakeholders) analysis (checking for consistency and completeness) definition (writing down descriptive requirements for developers) specification (creating an initial bridge between requirements and design). Eliciting requirements needs good people skills. High level managers, who have these kinds of skills, should be deeply involved in eliciting the customer's goals and making sure they are the constant focus of development. Eliciting is more than conversation. It is active questioning followed by mutual exploration of the business and technological ramifications of decisions. During the elicitation process, the senior managers should negotiate priorities, and take the time to define expectations. The focus should be on defining the customer's goals, and agreeing on ways to test whether the project meets those goals. Already you should be looking for high level test cases that can be answered with a yes or no. Your preliminary Analysis of requirements should question if a user goal is: Required or Optional Required goals must be stated as Shall, Must, or Will statements. Measurable or Vague Big, Small, and Friendly are not measurable. If it can't be tested, it's not a requirement. Determine how can you measure it. Singular or Mixed Watch out for compound requirements. Separate each requirement to as fine a level as possible. Make lists. All the while, you are providing Definitions. You must agree on users of the system, their terminology, workflow, and environment. This must be written in imperative form, using consistent wording and structure. Each requirement gets a unique identifier that will not change throughout the course of the project. Specification is where you work with designers and developers to describe the actual system that will meet the user goals. Everything from prose, to tables, diagrams, and development resources must be detailed. Throughout, write test cases to prove each requirement. As you refine the requirements, group them according to function and structure.

Specify Functions and Structures

A collection of requirements define the characteristics or features of the desired system. A 'good' list of requirements generally avoids saying how the system should implement the requirements, leaving such decisions to the system designer.

For each User Goal, you have derived a variety of required functions.

Write these functional requirements as testable imperative statements. For each test, describe the environment where the test takes place and the outcomes.

This generates the structures required to support the functions that meet the user goals.

List these structures and describe their parameters in testable statements.

IMPORTANT TIP

• Use proper sentence structures and select words and phrases based on explicit definitions, not what the popular culture thinks they mean. Define your terminology early and often.

Note from Technical Writer: Improve Clarity

Simple Use of Word Order

The system (subject) will (auxiliary verb) save (main verb) the file. (object)

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 three punctuation marks, re-write it to make it 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 it down

• Chunk the information to the level developers will understand.
• Sort the chunks into understandable 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.

Goal, Functions, Structures...Example You're talking with the users of the system, and find out that they're very worried about security. "I don't want no one looking at none of our stuff." From this you can extract the following functional and structural requirements. User Goal Keep information private Functional Requirements Sec-010. Only authorized users shall access the system Sec-020. The system administrator shall create, edit, and remove user accounts and access rights. Sec-030. .... Structural Requirements Sec-070. The system must validate users by unique identifier and password. Sec-80. The system must allow system administrators to Sec-81. *Create, edit, remove user accounts Sec-82. *Assign, update, revoke access rights Sec-90. ....

Testability

User goals have to be tested against the functionality of the system. It's how the user knows they're getting what they're paying for. This is where most projects seem to begin their documentation process, analyzing a system by its structure, trying to deduct the functionality, and guessing at the goals of hypothetical users.

That doesn't work very well. Your team will be trapped in a test, fix, test, fix pattern until the users give up or the team quits. Either way, it's the kind of project everyone hates. It doesn't have to be that way.

If a requirement isn't testable, it's not valid.

Develop your tests with your users wherever possible. Be sure to let them describe the actual environment where the product will be used. Listen again for their end goals, and make sure the system lets them achieve those goals without making them feel lost or dependent on experts.

You have to be able to derive a test for each user goal before the development begins. This allows you to both test the requirements, and give the developers concrete specifications of what is expected. In addition, if you follow common standards, you can create much of the content of the user guides, help files, test cases, and future maintenance and help desk reference.

The key is identifying not only the simplified user goals, but also the underlying cases where that goal can either be met or blocked.

This means that each goal has to be assigned to one or many tests. The tests validate different aspects of the goal.

For the user goal of keeping their information safe from outsiders, you'd get the following requirement.

Requirement ID	Requirement Description
Sec-010	Only authorized users shall access the system

This requirement leads to several obvious test cases.

Requirement ID	Requirement Description	Test Cases
Sec-010	Only authorized users shall access the system	Sec-010 Types of Test Cases Attempt to log in with 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 ....

Writing Simple Test Cases

Simple Test Cases 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. Learn more about Falsifiability. Use this standard format for writing test cases. Test Name and Requirement ID Prerequisites Steps Outcome The Test Name is a short description, like "Logging In". The Requirement ID shows the tester what user goal must be met, so the test can be validated against requirements. Prerequisites list all the hardware, software, data, and access rights, or other environmental conditions that have to be presented before you can begin the test. System Login GUI UserID Password Steps are numbered lists of actions to reach a goal. Write steps as user instructions. Type your User Name Type your Password Click OK Outcome states what must happen. This must be answerable with a Yes or No. The system logs in valid users. By writing each test case so it ends in a clear Yes or No, you'll know that it's valid. If there is no way to prove the test FALSE, the test itself is not valid. When you are writing tests, which you can begin in the earliest stages of requirements gathering, you'll uncover additional functions and structures you would otherwise overlook. Writing your test cases early, even if you just start with a rough draft on paper at first while negotiating functions, will reduce project risk and identify conflicts and misunderstandings before they become a problem. Many tests can be extended by adding conditions. For example, when the input value is not valid, what should the system do? This is a conditional case. These types of tests are stated in the If, Then, Else format familiar to programmers. Your development team partners should be skilled at pointing out these kinds of edge conditions and exceptions that must be tested for system reliability.

Writing Clear Requirements

Remember your Reader Writing Clearly Target your writing to your reader. Developers want exact, clear, organized prose, tables and diagrams 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. According to Donn Le Vie, Jr., a good requirements specification accomplishes four goals: Shows you understand what the customer wants Requirements are the "customer's assurance" that you understand what needs to be done. You must therefore keep requirements up to date with the users. The purpose of the project is the users. By keeping them involved in your team, not just providing status reports but inviting them to contribute their time and ideas, you'll enjoy a much better outcome. Surprises must be avoided...never delay bad news, and your customers will trust you more. Chunk and sort the information Requirements break down into chunks and sort these chunks into logical gloms. These information chunks define the work, limit the scope, and orders the requirements in terms of priorities. Lead the Development Requirements each have a unique identifier, usually a combination of letters and numbers, that allow you to add more information and decisions as you progress through the software development life cycle. Each requirement is the parent to a number of following designs, tests, and user interfaces. This is why successful projects devote at least a quarter of their total effort to defining requirements and planning. Validate the delivery Requirements allow you to know when you are done. By checking the product you have created against the requirements, you can validate that you have met or exceeded your customer's expectations.

When you write requirements, you'll mostly be using imperatives. Imperatives express direct commands, requests, and prohibitions. In many circumstances, using the imperative mood may sound blunt or even rude, but in technical communications they are normal.

Note from Technical Writer: Remove personification - "they"

Use

Using a consistent format may be boring, but it's accurate and saves you time and arguments over how to word things. Use the Subject + Auxiliary Verb + Main Verb + Object formula wherever possible.

Auxiliary Verbs

• Must
• Will

Strong Commands	Must, Will
Strong Prohibitions	Must not, Cannot, May not, Shall not...

• Use simple word order:

Subject + (strong command auxiliary) + Main Verb + Object.

The technical writer will write using proper grammar and tone.

Remember: Technical writers do not personify inanimate objects.

https://www.e-education.psu.edu/styleforstudents/c1_p15.html

"A related issue is the use of unintentional personification—i.e., assigning human traits to inanimate objects—in technical writing. In a phrase such as "when the drillstring feels the weight," the seemingly literal claim that an inanimate object such as a drillstring "feels" anything is clearly inaccurate. Similarly, a sentence such as "Boeing stock enjoyed a 2% increase today" could imply that stocks have emotions. Although such a sentence may well appear in the daily newspaper, its tone would not suit a technical paper. In technical writing, avoid unintentional personification, which is always revealed by the verb you use to express a noun’s action."

Avoid

Weak Suggestions	Should, Can, May, Alternatively...
Generalities	Big, Small, Easy, Friendly...
Ambiguous words	Shall

• Weak suggestions are optional, and not a contractual part of the system requirements specification.

• Generalities have no place in a requirement specification. If it cannot be measured or tested, it must be restated.

• The word shall might mean must, may, should or can, depending on who is using it. It is therefore best avoided entirely.

Be Strong and Clear Shall, Must, Will, Should Here is the NASA terminology recommendation for writing clear requirements: Shall is usually used to dictate the provision of a functional capability. Must or must not is most often used to establish performance requirements or constraints. Is required to is often used as an imperative in specifications statements written in the passive voice. Are applicable is normally used to include, by reference, standards or other documentation as an addition to the requirements being specified. Responsible for is frequently used as an imperative in requirements documents that are written for systems whose architectures are already defined. As an example, "The XYS function of the ABC subsystem is responsible for responding to PDQ inputs." Will is generally used to cite things that the operational or development environment are to provide to the capability being specified. For example, "The building's electrical system will power the XYZ system." Should is not frequently used as an imperative in requirement specification statements. However, when it is used, the specifications statement is always found to be very weak. For example, "Within reason, data files should have the same time span to facilitate ease of use and data comparison." (emphasis added TWFred 07:34, 15 December 2007 (UTC)) In disagreement with NASA, the US Government's Plain Language group recommends against using the word shall entirely, as it is not clear to most readers what it means. There are hundreds of lawsuits that center around the meaning of shall."Shall and must". plainlanguage,gov. Retrieved August 4, 2014. Strong Commands Commands give a direct order. You must eat all your food, is a command. The system (subject) will (auxiliary verb) save (main verb) the file. (object) Note: The second person (you) is always implied, so Eat all your food has the same meaning. Commands are the primary tool of requirements writers. They are strong and definitive. Note from Technical Writer: Remove personification - "they" Commands tell the developers what to make, and how to test it. Testing the commands against the deliverable is how customers check 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: Must The strongest verb is Must. It leaves no room for doubt that what follows is a necessity. Will Use Will for a statement of fact. In many requirement specifications (particularly in software), the words shall and will have special meaning. Most requirement specifications use the word shall to denote a requirement. The word will is reserved for a statement of fact. However, some documents deviate from this convention and use the words shall, will, and should to denote the strength of the requirement. Well-written requirement specifications define these words near the beginning of the document. For example, on standards published by IEC (International Electrotechnical Commission), ASTM (American Society for Testing and Materials), IEEE (Institute of Electrical and Electronics Engineers), requirements with "shall" are the mandatory requirements, meaning "must", or "have to". The IETF (Internet Engineering Task Force) defines shall and must as synonymous terms denoting absolute requirements, and should as denoting a somewhat flexible requirement, in Request for Comments (RFC) documents. (See: Shall and will and RFC 2119) Strong Prohibitions You cannot stop at describing only what the user wants. You must also describe what the user wishes to avoid. This is especially true for safety warnings, loss of data, security considerations and other environmental factors. Strong Prohibitions Shall not Must not Cannot May not Do not IMPORTANT: In the command form, Can and May are weak, but used as a prohibition, Cannot and May not are strong. You may not put needles in your ears. The system cannot delete any files. Be sure to use X must not rather than No X must. The second does not actually prohibit anything, instead merely stating X isn't required to do something, but still could.

Get Rid of Weak Suggestions and Useless Generalities Weak Suggestions Weak Suggestions don't belong in a requirement specification. Suggestions and requests, in the pressure of developing a working system on time and on budget, will probably be ignored or badly implemented. Rewrite them in strong requirement language, or eliminate them. Avoid using Should May Can You will often find that weak suggestions are out of scope, or have not been analyzed. Either way, exclude them from specifications until they are clearly required and well understood. Useless Generalities How tall is high? How little is small? How big is large? This is the kind of discussion you will find yourself having with developers and testers if you include ambiguous terms in your requirements. Generalities must be avoided wherever possible and replaced with specific measurable reference points. How you convert a generality into a specification depends on the context. Here are some examples: Too general: Enough memory for the users. Clear: The system must provide 20gb of free hard drive space for each user. Too general: The system shall shut down quickly. Clear: The complete power down sequence shall last no more than five (5) seconds.

Traceability

With time, requirements will usually change.

Customers change their minds. The market changes and demands additional requirements. Developers find new solutions that impact 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. As long as you allow for the system to expand, use whatever is reasonable for your audience.

For example, if we create requirements for a pocket calculator we could immediately find the following types of requirements:

• Size
• Math 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 centimeters.
S-020	The calculator must be no longer than 15 centimeters.

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 centimeters.
S-011	The calculator must be no wider than 12 centimeters at the bottom.
S-020	The calculator must be no longer than 15 centimeters.
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.

What is important is to construct your Unique Identifiers so that you can add more items. In this example, each UniqueID 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 your Unique Identifiers. Once an item has an identifier, don't change it. (For this reason, you cannot use your word processor's auto-numbering tools.)

Use Strong Words and Phrases

• Use the most simple words appropriate to the intent of the statement.
• Use imperatives correctly and be consistent. Remember, "must" prescribes, "will" describes, "must" and "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. It's 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."

Use References and Standards

• Identify all external documents in the section of the Software Requirements Specification (SRS) designated for that purpose by the appropriate Data Item Description (DID). For DI-IPSC-81433 and NASA DID-P200 its Section 2.
• 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, and 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 unique citation identifier when referencing information in the cited document. For example: " as defined by Section 3 of reference document 2.14."

Use Tables, Diagrams, and Lists

• Title and Identify each table and chart by a unique identifier.
• List each table and chart in the SRS'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. No surprises!
• Explain each aspect or element of the table or chart (columns, rows, symbols, blanks, etc.) from right to left then top to bottom. No puzzles!

Building and Maintaining Usable Requirements

A requirement is a singular information “chunk” of what a product or service should do or be. It is most commonly used in systems or software engineering. It identifies a necessary attribute, capability, characteristic, or quality that must be of value and utility to the end user.
Requirements show what structures and functions are necessary for the particular project.

Well written and planned requirements are essential to the successful development of every project. The format doesn't matter so much as the fact that the requirements are:

1. Unambiguous
2. Trackable
3. Updatable

Requirements are typically placed into these categories:

• Functional requirements describe the functions that the system must execute;
• Structural requirements constrain or support the solution. Structural requirements are sometimes known as constraints, quality, or even, "non-functional" 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. Note from Technical Writer: Remove personification - "they"
  

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. In this workshop we use the term User Goal.

The continuing requirements process has three repeating activities:

• Elicitation – the developer must validate the end user’s requirements for the project by showing progress, asking questions, and drawing out additional detail.
• Analysis – the requirements must be evaluated for accuracy, completeness and reachability by discussion between the developers, managers, and the end user.
• Recording – the requirements must be recorded flexibly, leaving room for additions and revisions. Use an open numbering/ID system for this.
  

Read more about NASA requirement recommendations)

In the real world, a working requirement specification never stops being edited and updated. It's not an artifact, but a workspace where users, designers, developers, and managers can share their ideas and come to agreement.

For requirement specifications to be useful, they must be used, and then tested.

Note from Technical Writer: Remove personification - "they"

Maintaining Good Requirements Characteristics of good requirements Good requirements 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 resources, and time. Verifiable – Can be verified by test, inspection, review, analysis, simulation or demonstration. Traceable - Has a unique identifier and is tracked through the entire SDLC. Record all requirements which are necessary even if you think they are "common sense". Note from Technical Writer: Remove personification - "they" Your requirements specification document must have a clear structure. Your customers, developers, and testers should all be able to find what they're looking for within thirty seconds. The requirements specification is a project deliverable whether or not it is required by a customer. Like any project deliverable, it must be verified. Ask your colleagues to review it. It's a good practice to have software architects, test engineers, domain experts, and customers review your specifications and provide feedback early and often. The most important aspect of requirements specifications is that they are USED AND TESTED THROUGH THE WHOLE LIFE CYCLE. Note from Technical Writer: Remove personification - "they"

Learn More…

• Requirements — Wikipedia
• Requirements Analysis — Wikipedia
• Capability Maturity Model — Wikipedia
• Software development lifecycle
• Writing Software Requirements Specifications — TechWR-L: Empowering Technical Writers Since 1993
• Writing Effective Requirements Specifications — NASA
• Requirements: An introduction — IBM
• Writing good requirements is a lot like writing good code — IBM
• Painless Functional Specifications - Part 4: Tips — Joel on Software
• Writing Quality Requirements
• Manage and Trace Requirements (Available via Web Archive, while site is unavailable)
• Defense Standard — Wikipedia
• Software performance testing — Wikipedia
• Software verification — Wikipedia

Links to Templates and Examples

Using a template saves you time and helps you to organize your work. If your organization already uses a template, so should you. If your organization doesn't have a template, you can download and adopt a free template according to your needs.

Using a template should not restrict you. Consider template as a guideline and adopt it according to project needs.

Read the very short RFC 2119 for a good definition of key words in writing requirements.

Requirements Examples

• Axia-Consulting Human Resources Example
• XML Services (XS) functional area of the Defense Information Infrastructure (DII) Common Operating Environment (COE)
• Military standard documentation
• Ken Rigby's DI-IPSC-81433 Software Requirements Specification

Free Template Downloads

The following links contain templates that when last checked are free to use and modify:

• Project Connections has some free templates as well as a paid subscription option.
• Process Impact Templates with a suggested donation to Norm Kerth
• A Canadian Government Template that is very flexible.
• A Template from the Texan Project Delivery Framework

Example: Asimov's Three Laws of Robotics

1. A robot may not injure a human being or, through inaction, allow a human being to come to harm.
2. A robot must obey orders given to it by human beings except where such orders would conflict with the First Law.
3. A robot must protect its own existence as long as such protection does not conflict with the First or Second Law.

Discussion Questions

1. How does Asimov identify a strong commands?
2. How does Asimov identify a strong prohibitions?
3. How would you break these laws down into smaller requirements?
4. How would you test these requirements?
5. Are there any unclear terms that you can further define?
6. What other "Laws of Robotics" would you add?

Subject classification: this is an information technology resource.

Subject classification: this is an engineering resource.

Subject classification: this is an English language and literature resource.