Technical writing specification
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.
Read more about project management strategy.
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.
- Does the requirement focus on what is required rather than a solution?
- Is the requirement easy to understand and difficult to misunderstand?
- Does the requirement contain simple, short, unambiguous statements?
- Is there an example illustrating the requirement? Is it needed?
- Is there a visual figure illustrating the requirement? Is it needed?
- Does the requirement contradict with any other requirement?
- Is the requirement complete (without requiring a reader to look for information elsewhere to understand the requirement)?
- Is each requirement uniquely identified?
- Can the requirement be tested?
- Can the requirement be traced to and from a business objective?
- 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.
Highly successful projects write test cases before they write code. 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
Small and frequent repetitions of this life cycle allow you to grow the system organically, building on previous success and constantly ensuring that you meet the user goals.
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:
- Analysis and Planning
Building the Idea
- Testing and Integration
Using the Idea
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.
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.
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. 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.
- Functional Specifications tracked to User Goals
- Workflows and Dataflows
- User and System Environment Constraints & Limitations
- Data Structures, Elements, Interfaces, Inputs, Outputs
- Performance, Safety and Reliability
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
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.
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:
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.
Use Simple Word Order
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 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.
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
Writing 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.
Steps are numbered lists of actions to reach a goal. Write steps as user instructions.
Outcome states what must happen. This must be answerable with a Yes or No.
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
According to Donn Le Vie, Jr., a good requirements specification accomplishes four goals:
Show what the customer wants
Chunk and sort the information
Lead the Development
Keep Requirements Up to Date with the Users
Validate the delivery
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.
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.
|Strong Commands||Shall, Must, Will|
|Strong Prohibitions||Must not, Cannot, May not, Shall not...|
- Use simple word order:
Subject + (strong command auxiliary) + Main Verb + Object. The system shall save the file.
|Weak Suggestions||Should, Can, May, Alternatively...|
|Generalities||Big, Small, Easy, Friendly...|
- 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.
Shall, Must, Will, Should
Here is the NASA terminology recommendation for writing clear requirements:
(emphasis added TWFred 07:34, 15 December 2007 (UTC))
Commands give a direct order. You must eat all your food, is a command.
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. 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:
The strongest verbs are Shall and Must. They leave no room for doubt that what follows is a necessity.
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.
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.
IMPORTANT: In the command form, Can and May are weak, but used as a prohibition, Cannot and May not are strong.
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.
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.
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:
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:
- Math Functions
- User Interface
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, "shall" 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".
- 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:
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.
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.
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.
Characteristics of good requirements
Good requirements are:
Record all requirements which are necessary even if you think they are "common sense".
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.
- Requirements — Wikipedia
- Requirements Analysis — Wikipedia
- Capability Maturity Model — Wikipedia
- How to Design Software With Bad Requirements
- 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.
- 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
- A robot may not injure a human being or, through inaction, allow a human being to come to harm.
- A robot must obey orders given to it by human beings except where such orders would conflict with the First Law.
- A robot must protect its own existence as long as such protection does not conflict with the First or Second Law.
- How does Asimov identify a strong commands?
- How does Asimov identify a strong prohibitions?
- How would you break these laws down into smaller requirements?
- How would you test these requirements?
- Are there any unclear terms that you can further define?
- What other "Laws of Robotics" would you add?