Requirements: Writing Specs That Save Time and Money

Writing clear, concise, and testable requirements is critical for ensuring that your project meets its goals efficiently. In this post, we’ll explore best practices for crafting effective requirements and how using the right tools, including AI, can streamline the process.

In embedded systems engineering, the functional and non-functional aspects of a new product are often described in natural language. While this informal approach can be useful in early discussions, it tends to cause problems when writing formal specifications. Common issues include unclear behaviors, contradictions, overly complex wording, missing features, and cognitive overload.

A better way to handle these challenges is to write specifications as a list of requirements. Requirements are clear, precise statements that define features or behaviors a system must meet to function properly. By using a structured approach to writing requirements, you can ensure that your specifications are clear, concise, and unambiguous.

Requirements Required

In today’s technical environment, using requirements is not optional. They are essential for ensuring project success by eliminating ambiguity, identifying potential issues early, and providing a clear framework for testing and acceptance. Requirements aren’t just a good practice; they are a necessity in any serious engineering project.

Without well-defined requirements, a project is left open to misinterpretation, inefficiencies, and increased risk. Whether it’s a small embedded system or a large, complex application, requirements are required to ensure that the end product meets its objectives.

What is a Requirement?

A requirement describes a specific feature or behavior that a system must fulfill to operate correctly. It’s important to distinguish requirements from other useful but non-essential information, which may provide context but does not directly describe how the system should behave.

Characteristics of Good Requirements

For a requirement to be effective, it should follow these key principles:

Single Focus: Each requirement should address only one feature or behavior, avoiding mixed or compound statements.
Conciseness: A requirement should be as brief as possible while still providing all necessary details. Overly wordy requirements can create confusion. A single sentence is perfect.
Unique Identification: Every requirement must have a unique reference ID that remains consistent across the project. The ID must remain unique over the lifespan of the development program to ensure external documents can always point to it. Especially, the ID of a deleted requirement must never be reused.
Measurability: A requirement must be testable. If it cannot be verified through testing, it isn’t a true requirement.
Traceability: Each requirement should be linked to higher-level system goals or design elements to ensure it serves a meaningful purpose within the overall system.

Examples of Good and Bad Requirements

Understanding the difference between well-written and poorly written requirements is essential for producing effective specifications. Below are examples that illustrate common mistakes and best practices.

Example 1

The system should be fast.

This is too vague. What does “fast” mean? Without specific criteria, it’s impossible to test or verify. Write something more specific instead:

REQ-1234: Performance

The system shall process 100 transactions per second with a response time of less than 2 seconds under a load of up to 10,000 concurrent users.

This version is measurable and provides clear performance expectations.

Example 2

The device should work in different environments.

This is too broad. What exactly does “different environments” mean? It leaves too much open to interpretation. This is better:

REQ-1235: Temperature Range

The device shall operate at temperatures ranging from -20°C to 60°C.

REQ-1236: Humidity

The device shall operate at humidity levels up to 85% .

This version clearly defines the operational conditions, making them easier to test.

Example 3

The system should have a user interface that is easy to navigate, user-friendly, and should allow the user to input data, process the data quickly, and provide feedback in real-time. The interface should also display results in an easy-to-read format, and users should be able to export the results to multiple file formats including PDF, CSV, and Excel.

This requirement is too long and mixes multiple concepts, making it difficult to test and implement clearly. It should be split into several unambiguous requirements:

REQ-1237: User Interface

The system shall have a user interface that allows users to input data via text fields and dropdown menus.

REQ-1238: User Interface Reactivity

The system shall process input data and provide visual feedback within 2 seconds.

REQ-1239: User Interface Data Layout

The User Interface shall display results in a tabular format with clear labels and headings.

REQ-1240: Data Exports

The system shall allow users to export results in PDF, CSV, and Excel formats.

These clearer requirements break the long, confusing sentence into specific, measurable features, making it easier to implement and test each part individually.

Benefits of Using Requirements

Adopting a requirements-based approach offers several key benefits that can significantly impact the success of your project:

Encourages Logical Thinking: Writing clear requirements promotes a structured, logical approach to solving complex problems.
Identifies Issues Early: Clear requirements make contradictions, missing features, or ambiguities easier to spot early in the process, preventing costly revisions or redesigns later.
Avoids Unnecessary Features (“Engineer’s Toys”): Thanks to the traceability of requirements, each feature is tied to a higher-level goal or business need, ensuring that only essential features are developed. This helps prevent the addition of unnecessary “nice-to-have” functions that could waste time and resources.
Facilitates Testing: Each requirement can be directly linked to test cases, making unit testing and validation more efficient. This linkage helps streamline quality assurance efforts, ensuring that every feature and constraint is tested properly.
Simplifies Acceptance: A well-defined set of requirements provides a clear framework for verifying system conformity, streamlining the acceptance process for both internal teams and external stakeholders. This clarity reduces delays in final approvals.

Tools for Managing Requirements

Although it’s possible to write requirements in basic text editors, specialized tools offer significant advantages for organizing and managing them throughout a project’s lifecycle. To simplify, these tools are essentially word processors with specialized features for handling requirements.

Key features include:

Unique and Persistent Numbering: Specialized tools manage the unique numbering of requirements across the entire project, ensuring consistency even as the project evolves.
Linking Related Requirements: They automatically link related requirements, making it easier to navigate the complex relationships between specifications.
Traceability and Version Control: These tools often support traceability, linking requirements to design elements, test cases, or higher-level objectives, while maintaining version control as requirements change.

Popular tools include:

DOORS and Polarion: These comprehensive high-end tools are designed for managing complex requirement sets, with advanced features for traceability and version control.
Jira and Confluence: While not primarily designed for requirements management, these tools can be used to this purpose and offer powerful collaboration and tracking features.

Beware of using standard word processors like Microsoft Word or LibreOffice Writer to write requirements. These tools don’t natively offer a section numbering scheme that is suitable for requirements (e.g., unique IDs that persist across revisions and ensure consistency). While this can potentially be managed with custom macros, it adds extra work and complexity to the process.

AI Can Assist

While tools are invaluable, translating natural language specifications into formal requirements is still a complex task that requires human judgment. However, AI can assist by automating some of the more tedious tasks:

Extracting Requirements: AI can analyze specification text and extract potential requirements.
Assigning Unique IDs: AI can automatically assign unique numbers to requirements, ensuring consistency across the project.
Formatting Output: AI can format the extracted requirements into a standard template, making them easier to review and manage.

To simplify this process, we have developed a Custom GPT that converts natural language specifications into a list of formal requirements. RequirementGPT is available for free in the Goodies section of Embedded Expertise’s website. While it provides a basic framework for generating requirements, the output should always be reviewed and refined by an experienced engineer.

Why You Should Try RequirementGPT

RequirementGPT was originally designed to be an educational tool to demonstrate how requirements can be derived from natural language specifications. Now there is more to it.

Writing good requirements takes time and attention to detail, but RequirementGPT can help speed up the drafting process by generating a starting list of formal requirements based on natural language inputs. It saves you time by automating initial steps, but remember—AI tools are here to assist, not replace, human expertise. Reviewing the generated output to ensure accuracy and completeness is essential.

There are plans to improve RequirementGPT over time, so check back regularly for updates.

Key Takeaways

By writing specifications as clear, concise, and measurable requirements, embedded systems engineers can eliminate ambiguity, improve clarity, and enhance the quality of their projects. Following the guidelines in this post, along with using modern tools and AI assistance, will help you create robust specifications that form a strong foundation for successful system development.

For additional help, you can try out the RequirementGPT tool, available in the Goodies section of this website. It provides a simple way to convert natural language specifications into formal requirements, but remember to refine the results carefully for your project needs.

Should you still need help writing your specification, please seek professional assistance. Writing requirements requires practice, and we are here to help you write clear and testable requirements, ultimately saving you time and money. Our team can help ensure your project’s requirements are accurate, comprehensive, and ready for testing.