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:
Shows you understand what the customer wants
Chunk and sort the information
Lead the Development
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.
Subject + (strong command auxiliary) + Main Verb + Object. The system will save the file.
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:
Each of these types of requirements contains many sub-requirements, so you can put them into a table:
Calculator Size Requirements (1st draft)
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:
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 References and Standards
Use Tables, Diagrams, and Lists
Building and Maintaining Usable Requirements
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:
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:
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.
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.
Free Template Downloads
The following links contain templates that when last checked are free to use and modify:
Example: Asimov's Three Laws of Robotics