Multipart article

Wise Words About Writing Technical Requirements Documents

Preparing technical requirement documents (also known as product requirement documents) is a typical part of any project to create or revise a software system, or other types of tangible products. There are many benefits of investing time and effort into preparing a technical requirement document. This article discusses some of these benefits and includes tips for writing technical requirement documents. You’ll also meet three experts who offer their advice and experience: Rachel S. Smith, former Senior Interface Designer at the SCU Center for Distributed Learning, Renee Fellman, award-winning business turnaround expert, and Michael Shrivathsan, Vice President of Product Management at Accompa.

Additionally, you’ll find a brief description of other types of requirement documents that either overlap with technical requirement documents or are confused with them. There is also a discussion of Agile Modeling, which is one way to produce technical documents plus a short review of IT requirements for companies and educational institutions. 

While this article offers helpful guidance to help you create a technical requirement document, it’s also okay to do it ‘your way.’ Every company has different policies and practices for documentation. Make sure you know your company’s policies and develop a technical requirement document that works for you and your team. 
 


Ensure that your next technical requirements document is effective with a helpful checklist.
Free Checklist: Essential Checklist for Writing Technical Requirements Documents
Get it here


Why Create a Technical Requirement Document?

 

Rachel S. Smith, author of Writing a Requirements Document, explains that a technical requirement document, “Presents why a product is needed, puts the product in context, and describes what the finished product will be like.” For software projects, a technical requirements document generally refers to how the software will be built including the operating system it is being programmed for and other standards.

 

If you don’t create a technical requirement document, real problems can develop, according to Smith. These problems can include:

  • Building a product that doesn’t fill a real need.
  • Developing ‘feature creep.’
  • Having one group on the team think they are building an ant, while another group thinks they are building an elephant.

 

Renee Fellman, a Portland, Oregon-based business expert who specializes in turning around businesses on the brink of failure, has found that failure to adequately document technical requirements can cause serious problems for a company that impact their bottom line.

Problems that arise from not having technical requirements documentation can range from simple to complex. “In one company I consulted for,” Fellman said, “Vital FDA compliance issues weren’t being addressed because human resources had failed to do something as simple as assign the duty of taking care of regulatory affairs.”

 


The Value of Technical Requirement Documents

A technical requirement document empowers your team to come to a mutual understanding of what is required, technically, to make your project or product a success. Out of the 5 Phases of Project Management, technical requirement documents should be created during Phase 2 of your project’s life cycle. During this phase the scope of your project is defined and goals are set. Technical requirement documents will also provide information that will help you:


Expectations of Technical Requirement Document Preparers

Anyone preparing a technical requirement document should understand what comprises a ‘good’ system requirement and how to communicate this information in a clear way.

  • Keep the following points in mind:
  • Be creative about the sources you choose to explore as you analyze your technical requirements and always use your business need as a basic reference point
  • Help others understand your results by using easy-to-understand language
  • Use prototypes to figure out what you are missing
  • Make sure you understand the interrelationships, priorities, cost, implementation, and environmental consequences when you decide what to include
  • Define system boundaries 

Other Types of Requirement Documents Commonly Found in Business

In determining your initial list of technical requirements, be aware that there are other documents that are also being prepared by other teams within your company. These documents are about the same project but for different audiences. It’s highly possible that some of these documents may contain redundant information. You may feel that some items belong in your technical requirement document and not in the business or market requirement document, but don’t worry - you can have them in both. It’s up to you to create a technical requirement document that works best for your purposes. Make sure you gather the information that is most useful to you. 

Michael Shrivathsan, the Vice President of Product Management at Accompa, is an expert on types of requirement documents and their functions. 

 

“There can be some overlap between business, market, and technical requirement documents,” said Shrivathsan. “Depending on the organization, they may or may not use all these document types. At large companies (1,000 employees plus), they typically do use all three of these docs. Most mid-sized companies (200 employees or more) use at least two of them.” 

There may be important information in these other reports that can inform, influence, or create contingencies with your technical requirement document. Here are some other documents that may be created by other departments to support your project:

Business Requirement Documents (BRD)
Written by: Product Managers, Product Marketing Managers
Audience: Business Managers
Reviewed and approved by: C-level executives  

A business requirement document defines the project’s high-level business case and is usually prepared first.

A business requirement document defines the goal of the project from the viewpoint of the business. Documentation for this phase delineates the business goals at a high level. Members of this team should have met with appropriate business managers at your company or your client's company to gather the required business information that focuses on both your business’ and customer’s need.
 
From the business requirement document, you may learn the following information that could help you with your technical requirement document:

  1. The nature of your customers’ needs
  2. How meeting these needs aligns with your company’s mission
  3. How your product, system, or software will solve your customer’s needs at a high level
  4. A portrait of the relationship between all the stakeholders in the project, through appropriate flow, organizational charts, or diagrams is recommended to ensure clarity

 
Market Requirement Document (MRD)
Written by: Product Managers, Product Marketing Managers
Audience: Business Managers  
Reviewed and approved by: Director-level 
A market requirement document adds more information to the BRD, in terms of what the market needs, and pinpoints the current market landscape for products or programs like the one you are developing. Knowing something about what’s already out there, how it’s marketed, and to whom, can help you determine gaps in other product features.
 
From the market requirement document, you may learn the following information that could help you with your technical requirement document: 

  • The type of product being planned
  • Customers being targeted
  • Personas that define:
    • Customer characteristics
    • The challenges they face
    • How your proposed product will help solve these challenges
  • Competing products and their advantages and disadvantages
  • Ways in which your product will be better

 
If no one in your company is preparing the above reports, you may have to do some extra leg work to get the full picture of the universe in which your product will exist.


Technical Requirements Should Focus on Desired Results

Software development technical requirements include components such as development planning, technical architecture, software testing, and deployment. Fellman advises that good technical requirements documentation starts by focusing on the results you want and not overly focusing on the process. Why? Because where you want to go determines everything about how you are going to get there. For example, you wouldn’t take a camel to arrive at the peak of Mt. Everest, but you might ride one if your end-goal was to reach an ancient tomb in the Egyptian desert.
 
Fellman cautions, “Failure to ask the right questions before you start preparing the technical requirements document can lead to a document that doesn’t actually solve the problem you’re looking to solve.” 
 
Questions, of course, will vary depending on your customers, your company, and the intended service or product, but for technical requirement documents explore what you want your new system or software to accomplish—especially from the point of view of the user. You may want to consult with your developers and ask, from their viewpoint, what is doable and what is not.

 


Templated Technical Requirements Checklist Are Valuable Organizational Tools

Using a templated checklist, such as the Requirements Collection Checklist from Smartsheet, can help you stay focused on the types of information you should be collecting as part of your technical requirements analysis.
  
Be sure to include:

  • Functional requirements and the tasks it will perform
  • Driving dates in terms of milestones
  • Physical requirements for a tangible product such as size, weight, color, shape, texture and ruggedness
  • Specifics of the technical environment
  • Data requirements
  • External interfaces
  • Compatibility/portability
  • Maintenance

Gather Information from Diverse Groups 
Smith suggests information for these kinds of documents can come from a variety of sources, including end users, customers, developers, and other stakeholders. Information can be collected through interview, surveys, questionnaires, research, or even roundtable discussions between and within teams.

Employ Usage Analysis
Identify the types of users who will be using your product and figure out their usage patterns. This will help when it comes to determining any requirements necessary for the level of performance you wish to achieve. 

Develop Use Cases 
Models for interactions by typical users should be included in a technical requirement document or in the business requirement document, using case diagrams and case reports. 

Explore Needs and Desired Outcomes 
Consider gathering the following types of information for your technical requirements document:

1. Define end user expectations and needs, and how the product will be used in the real world. Ask questions (here are some samples):

  • What core problem will your product or software solve for your audience?
  • What do you want people to accomplish while using your product or software?
  • How will lives be made easier and more productive?

2. Define the team structure and contingencies 

  • Which team members are responsible for aspects of the work? (Remember Fellman’s example above and make sure all the important job responsibilities are assigned.)

3. Define the product  

  • Use mock-ups, narratives, or lists.
  • Clearly state interface requirements.
  • Clarify customer or client requirements especially if product or software is being built to a client’s specification.  
  • Define development stages. 
  • Include specific steps to completion, and create an initial schedule that can be refined as more details are discovered and decided.
  • Identify contingencies by exploring which parts of the process are dependent on each other and why.

4. Create a prototype to help clarify the outcomes users anticipate from the new product or system when complete


5. Define the entire lifecycle of product development, including people, process, software and technology development, change management


6. Make sure each system requirement describes:

  • The relevant function it performs.
  • Any kind of limits, in terms of design, legal, or regulatory constraints or risks.
  • Environment design requirements for operational location, use, or storage.

Consider System Qualities
Consider the following system qualities when describing the quality of service you need to meet your business and user requirements.

  • Availability - How much ‘uptime’ you can expect your system to have based on your system’s resources, services, and accessibility to end users.
  • Latent Capacity - How your system will deal with unexpected peaks in usage independent of more resources.
  • Performance - Given specific load conditions of a range of uses, what will be the response time and latent capacity.
  • Scalability - How quickly can capacity and the number of users be increased or decreased, without changes in original architecture.
  • Serviceability - How easy is it to monitor, repair, and upgrade both hardware and software system components? Factors to consider include planning for downtime, opportunities for maintenance based on patterns of usage, critical times for service availability, schedules for diagnosis and monitoring.
  • Security - How secure is the system, including authorization and authentication of users and information during transfer?

Validate and Refine Your Technical Requirements

Once you have defined your technical requirements, take the time to validate and refine them. Smith said, “We looked at factors like: how many stakeholders requested a given requirement, how many other requirements were dependent on it, whether it would make the system easier to use or perform a function that users couldn't do any other way, as well as other qualitative measures.” 

For Smith, validating the requirements was a process of getting as many eyeballs on them as possible, listening to feedback, and discussing the implications of keeping or rejecting a given requirement. “There isn't really a shortcut. It’s all about involving key stakeholders and working with them to understand and resolve any differences of opinion.” 

Smith predicts you will never know if you’ve captured all the necessary requirements. “You’ll probably gather more than you need. But once you have them, prioritize them and work on the top-priority requirements that fit your time and budget. Sometimes it's not the biggest requirements that are the most important.”

Keep stakeholders in the loop  

Today, there are tools that give stakeholders a view into the development process directly, where they can see progress tracked visually, review (but not edit) requirements as they are being implemented, and test early prototypes. “Software development is such a tricky thing,” Smith said. “People get excited about features before they are developed, and they can be really disappointed if their expectations aren't met.” Therefore, keeping people informed and giving them early access and regular updates in whatever way works for them is key to end-user satisfaction once the product is released. 


Is Agile Modeling for You?

Agile Modeling (AM) is another way to create and document a model that can be deployed in the development of software-based systems and products. Its scope goes beyond technical requirements documentation to include the whole process and combines best practices based on the most effective values and principles for creating the best software possible, given time and budget.  

To learn more about Agile Modeling, here are some recommended books:


Technical Requirement Templates vs. Software

Templates are easy to use and the cost is right, but there are alternatives, as well. Shrivathsan’s company, Accompa, makes requirement document software that manages problems that could arise based on redundant or misconstrued information.

This software:

  • Tracks dependencies between these three types of documents. If something in the business requirement document changes, it can have a cascade effect on the market and technical requirement documents. 
  • It provides one repository to keep all information so that it can be easily consumed (Shrivathsan mentioned that at most large companies, this information can be fractured into multiple silos, making it very hard to find and use).

“For anything but the smallest projects, it is almost impossible to track these dependencies manually,” Shrivathsan said, “So an affordable software tool is needed.”


Advice for Writing the Technical Requirement Document

Writing technical requirements is a bit different from other standard business documents. There’s an art to writing them so that they can be understood by the people who will be using them to complete a project or build a new type of software. Here are some tips that can help you write useful technical requirements:

  1. Use simple, straightforward language so everyone has a common understanding of what you mean.
  2. Be concise. Start with an introductory paragraph, followed by bullet points to increase readability.
  3. Keep your sentence structure simple to convey only one main idea at a time.
  4. Sometimes a picture IS worth 1,000 words, especially if it simplifies a concept or shows the relationship of one concept to another.  

Technical Requirement Documents for Educational Institutions and Businesses

Some educational institutions and business have web pages on their sites devoted to the basic technical requirements for computer hardware, software, and browsers. If these basic technical requirements are not met, students, faculty, or employees will not be able access the intranet. In the case of students this means they can’t take online classes. In the case of businesses, it means employees may not be able to do their work.   

Information usually includes:

  • Minimum configurations for the Windows and Mac platforms, such as minimum processor or CPU speed, minimum memory, and type of operating system.
  • Speed of network connection for Internet access
  • Current list of supported browsers, plus links to download them
  • Current list of browser plug-ins, plus links to download them
  • Internet access information
  • How to register for a school or company email account
  • Required software

Smartsheet Templates Transform Your Technical Requirements Into a Working Checklist to Manage Any Project

Smartsheet is a work management and automation platform that enables enterprises and teams to work better. Having a reliable template to track and manage requirements can help make any project run smoothly. Use Smartsheet’s customizable Requirement Collection Checklist to turn your technical requirements document into an organic checklist that you can share with your entire team and stakeholders. Use the template to store, organize, and communicate new project requirements. Once all your information is entered into the template, you’ll have a foundation for your development process and the ability to track status, priority, and key dates. 

See how easy it can be to manage and track technical requirements and other business documents. 
 

Try Smartsheet for Free for 30 days


Wise Words About Writing Technical Requirements Documents

Try Smartsheet for Free