How to Create a Requirements Document and Nail Your Project

The Importance of Good Requirements

Have you ever wanted to have someone do a project for you, and that person couldn't see inside your brain? Was it difficult to write down even when you try? An engineering requirements document is the best way to solve that problem. When a company has a solution that it wants to implement, the requirements document shows what the product must accomplish to be completed successfully. It gives a clear explanation for what the solution must do, and is the means for helping both parties know when the project is completed. These constraints give engineers, designers, and other decision-makers a sphere with specific bounds to keep their energy focused and allow them to complete the task. Constraint feeds creativity and a good requirements document will not limit the solution's potential, but it will build the foundation that allows for an extraordinary solution.

A requirements document can change, but the more complete it is from the start the easier it is to be on the right track along the way. Many of the difficulties of a project come from people being on different pages and making decisions that don't align. Engineers hate doing work and then finding out that it needs to be redone because one of the underlying assumptions was invalid. Project managers hate assuming that something is almost done only to find out that it has to be done over again. 

Good requirements lead to faster completion, more efficient work, and lower costs. Besides these obvious resources saved, they also improve the well-being of everyone working on the project. Stress is minimized, energy is focused, and morale is improved.

Requirements from all angles

How to Determine your Requirements

The simplest way to create your requirements is to start with the most generic goals for the project. From there, you can break down each goal into specifics by asking what, how, and when questions. Occasionally who and where can also be helpful. These are the same questions that the engineers will be asking when working to execute the project, if you can answer them beforehand in the requirements document, then the project will progress much quicker. As you answer each question, consider if it is necessary. If it doesn't matter, give the freedom to the engineers to explore the best solution (that is what they are there for), but if you aren't yet sure what the answer to the question is, don't leave it out. Include the requirement with brackets [ ] around any estimated values and a note that more details will come and then work hard to define any uncertainties.

Once you have broken everything down and you feel that you have answered every necessary question, review your new requirements document and consider different requirement categories. Common requirement categories to be considered include

  • function
  • performance
  • user interface
  • operation environment
  • training
  • error detection and logging
  • personnel
  • safety
  • security
  • reporting
  • data collection and storage
  • future project expansion/growth

Engineering teams often have questions about what is expected or desired, but if they are confident that the requirements document is thorough, then they have the freedom to answer many of these questions themselves after considering the consequences and results. This results in a better final product that can be completed faster and more efficiently, saving you money.

Requirements document should be written with a diverse team. The team would ideally include multiple genders and ethnicities as well as members with and without technical backgrounds. This helps to see things from different perspectives and even though an individual may think that there is only one way to interpret a requirement, another member of the team may see multiple interpretations. This ensures that you get what you want and expect from your project.

How to Write Good Requirements

Requirements should be clear and concise and rarely more than a single sentence. If further explanation is needed, then use a directive or rationale statement. A directive points to supporting data - "The system shall create an audible alarm if the motor temperature is not within the bounds found in appendix A.3" A rationale statement is a statement directly after the requirement that allows the requirement to stay concise but give valuable information to the development engineers - "The system shall always set all outputs to zero before shutting down. Rationale: Some errors may shut some hardware down abruptly leaving other hardware in a dangerous state. For this reason, the program must check to see if this has occurred and override any built in shut downs to ensure that the system is not left with a high voltage power supply in a dangerous state."

When creating a rationale statement, begin by asking yourself the following questions:

  • What is an aspect of this requirement that could be a source of contention?
  • How am I choosing to address that aspect in the requirement?
  • What is the evidence to support my decision?
  • What other requirements might have some effect on the interpretation and implementation of the requirement and thus should be referenced in the rationale?

Requirements are defined using the word "shall" while "will" defines facts and "should" states a goal. Using this terminology and being consistent throughout the document makes it easier for engineers to create the systems that you expect.

Each requirement must be necessary, verifiable, attainable, and clear in order to be useful for development.

Necessary - What is the worst thing that could happen if this requirement were not included? If you do not find an answer of any consequence, then you probably do not need the requirement.

Verifiable - How will this requirement be verified? There must be criteria for acceptance with each requirement.

Attainable - Is the requirement technically feasible and fit within budget, schedule, and other constraints? If you are uncertain about whether a requirement is technically feasible, then you will need to conduct the research or studies to determine its feasibility. If still uncertain, then you may need to state what you want as a goal, not as a requirement.

Clarity - Does the requirement simply express a single thought? Simple sentences will most often suffice for a good requirement and minimize ambiguity.

Some final tips that will save you from some headache include:

  • consider the consequences of loosening tolerances
  • couple requirements as little as possible to minimize ripple effects when changes are made
  • consider how the successful implementation of a requirement will be verified
  • use brackets [ ] around estimate values rather than leave completely ambiguous "TBD" points in a requirement
  • avoid using weak, subjective words such as: efficient, powerful, fast, effective, few,  most, strengthen, enhance

Formatting your Requirements

Now that you know what you need to include, you need to express the requirements in a simple, recognizable way. Below is a pattern that gives you a framework to do just that.

Project Unique ID: <Syntax Pattern>

formatting table

Turning your Requirements into a Document

A good requirements document should have at minimum a cover page, section headings, essential guidelines for the content in each section and a brief explanation of the version control or change order process. This layout gives you plenty of flexibility to fit the document to your project rather than trying to tweak your project to fit the document. The sections can be organized by workflow, schedule, function, process, or many other options. This will depend on your project as well as the way you think so that you can make the most sense of what needs to be included. Remember as you are building the document to consider all applicable categories:

  • function
  • performance
  • user interface
  • operation environment
  • training
  • error detection and logging
  • personnel
  • safety
  • security
  • reporting
  • data collection and storage
  • future project expansion/growth (configurability)
  • etc.

The version control process is important to specify. The idea is to create a process that keeps items from falling through the cracks. It is also important to determine how simple or difficult you want it to be to make changes.

The last part of the requirements document writing process is to have it signed off by the stakeholders.

checklist

Checklist

This is a checklist that you can use when creating your requirements document. The "Each Requirement" section includes questions that can be asked about individual requirements, and the "Overall Document" section has things to consider throughout the process and questions to answer as you approach completion of the document. 

Overall Document

Is the terminology consistent throughout the document?

Were all requirement types considered?

Does the document include a change order process?

Each Requirement

Can requirements only be understood one way?

Can requirements be verified upon implementation?

Are requirements stated using "shall"?

Do requirements specify "what" rather than "how"?

Are requirements free from indefinite pronouns (e.g., this, these, it)?

Does each requirement only express one thought?

Are requirements stated simply and concisely?

Are undetermined values estimated and placed within brackets [] ?

Are requirements free of ambiguities? Examples of terms to avoid: "as appropriate" ... "but not limited to" ... "be able to" ... "be capable of."

Are requirements stated positively when possible as opposed to negatively (e.g., "shall not")?

Are requirements free of passive voice?

https://ep.jhu.edu/about-us/news-and-media/writing-good-requirements-checklists

https://qracorp.com/write-clear-requirements-document/

https://www.reqexperts.com/wp-content/uploads/2015/07/writing_good_requirements.htm

Haden Heath

Associate Systems Engineer, Business Development Engineer

Haden developed an interest in problem solving and looking for opportunities to innovate while studying at Brigham Young University. He earned his BS in Mechanical Engineering and a Business Management minor. During his schooling he worked on projects including a LabVIEW VI built to determine thermal properties using fluorescence from green lasers and a bullet-proof barrier for law enforcement that can be folded down and stored in the trunk of a vehicle.

Haden joined the Endigit team in 2018 immediately following his graduation from BYU and hopes to help expand the business while developing LabVIEW software.

Haden enjoys spending time with his wife and daughter, especially when doing outdoors activities. Hiking, camping, boating, hunting, and sports are among his favorite activities.

Add new comment