Technical Writing Guidelines for Documenting Business Requirements

The purpose of this article is to assist business analysts in writing business requirements. This article provides six guidelines on technical writing. The six I cite here are the major ones I consider when writing a business requirements document (BRD).There are, of course,other technical writing guidelines; for comprehensive texts, see Further Reading (1).

Introduction

Last year, I wrote about verifying requirements documentation (2) in terms of best practices. Note I used the word verify – not validate. Verifying requirements focuses on stating the requirements right – not on stating the right requirements. In this article, I want to continue the topic by discussing technical writing.

Below is my mind-map (Figure 1) on this article. Mind-maps are helpful tools in organizing and remembering material. Refer to my mind-map as you read this article. However, I encourage you to develop your own; using your key words and images arevital to you remembering the material.

My mind-map has a central idea of “Technical Writing Guidelines for Documenting Requirements.” Projecting from this central idea are seven branches. With the exception of the branch “Style,” each branch represents a guideline with my key words and images. Review my mind-map in the following manner:

1. Starting with the branch marked “Style”
2. Work your way around the central idea clockwise
3. Read the article
4. Go back, review my mind-map again
5. Develop your own mind-map

Figure 1. Mind-map on Technical Writing Guidelines for Documenting Requirements

Style
Even though the BRD is a business document,business analysts need to follow technical writing principles. There are two major requirement writing styles: business and technical. Business writing is usually one-to-one: writtenby one person for one person. Technical writing on the other hand is many-to-many:a collaborative effort for an audience. A business requirements document (BRD) is typically written by several business analysts, reviewed by several subject matter experts, and read by a wide set of stakeholders.

• Project sponsors and other stakeholders
• Project managers and other team members
• System analysts, testers, and other IT personnel

Due to the composition of the BRD, business analysts need to provide overviews in the form of introductions and summaries. The BRD covers various types of elicited business and user requirements. From these elicited requirements, business analysts developand document solution requirements as system functional capabilities, non-functional conditions, and transitional needs. Business analysts also document associated figures and tables, models, and business rules in the BRD.

Six Technical Writing Guidelines

1. Grammar

Grammar deals with structural rules on how we compose oral and written language. In technical writing, we strive for clear communications that provide a single interpretation. This is no easy task. Someoneonce said that no matter what you write readers will interpretit several ways. Unfortunately, the misinterpretations of documented requirementscausemosterrors in development. Technical writing grammar attempts to minimize these misinterpretations. Below are specifics:

• Use less than
  •  25 words per sentence – short, clear points
  •  8 sentences per paragraph – focused main thoughts
•  Use positive statements – negative statements cause confusion 
  
  • Use “The system must ensure all users gain access via a valid password,” instead of    “The system must not allow any user to gain access via an invalid password.”
• Use words that are
  •  Consistent – use one word for objects
  •  Defined business terms in a glossary (business rules); remember readers live in different work bubbles
    • Jargon
    • Abbreviations
    • Acronyms
• Use verbssuch as
  • Must or Shall–for mandatory items
    • The system must generate audit reports daily.
  •  Should, Could or May–for optional items
    • The system may generate audit reports daily.
  •  Will – when another organization or project provides the item
    • The Accounts Payables project will provide all interfaces and protocols to the customer application.
• Use descriptors
  •  Specifics –narrows interpretations
    • The solution must provide access to all users via an 8-12 character user-name and an 8 character password.
  •  Metrics – particularly for system conditions (non-functional requirements)
    • The solution must be available during business hours (9 AM through 5 PM EST) Monday through Friday.
•  Use the active voice
  •  Active – noun/verb sentences
    •  The accountants must authorize all payments.
  •  Passive – hides the subject that causes action
    •  All payments must be authorized.
• Use gender neutrality – eliminate he/she
  • Titles – use the name of role
  •  Plurals – use group pronouns (we, they, them)
    •  Business analysts decompose the system features after the meeting. From the features, they develop solution requirements.

2. Lists
Lists are quite useful in writing requirements and business rules. Typically,business analysts itemize many things in the BRD. But when a series of items are buried in text, readers have difficulty understanding the context. An alternative is to use lists.

There are two types of lists: numbered and bullets. Their application is simple. When there is a priority, sequence, ranking, or process steps involved, the list needs to be numbered. In the absence of this, bullets are the preferred method.  

3. Figures and Tables
Visuals help communicate complex topics. Figures may be in the form of graphs or actual pictures. Each figure needs to have a

• Title – unique references for figures and tables
• Scale – units of measure (dollars, days, work units)
• Legend – unique plot titlesif multiple plots are used
• Focus – single intent (use separate figures and tables for each intent)

Tables in particular help clearly state various conditional business rule combinations and resulting actions. They make business rule conditions much more definitive than a series of condition statements.Imagine how confusing a series of business rules would be with nested if statements. Note that the table format below also provides a way to identify the number of combinations for testing business rule conformance.

4. Models
Models are an integral part of any BRD. Theyare visuals that portray reality (AS-IS) and visions (TO-BE) through diagrams, text and metrics. Note, without the text and metrics, these visuals are just diagrams. Some models are dynamic and consist of action items called tasks. Use action verb (optional qualifier) noun phrases to name these tasks.

 
5. Simplicity
Requirements are capabilities, conditions, or transitions that may need to conform to business rules. It is a best practice for requirements to refer to business rules. That is, document the requirements and business rules separately. This allows the business analyst to change them independently. Note each requirement and business rule need to have a unique tag for referencing.

From a technical writing point of view, this separation simplifies the requirement statements. For requirements that need to conform to business rules, reference business rules by their unique tag, rather than restating them; note a requirement may refer to multiple business rules. Document needed business rules separately in a catalogue, a table, or a decision model. Note this also holds true for process models and their associated business rules. 

 
6. Separation
Business rulessometimes involve calculations. Highlight calculations by separately documenting formulas on a different line from the explaining text. This ensures that readers can easily reference the formulas. Furthermore, make the formulas distinct from the text by using italics.

 
Summary
This article is a continuation of my previous publication on verifying requirements documentation. My focus here is on sixtechnical writing principlesillustrated with some examples; I cite comprehensive references in the Further Reading. Even though the BRD is a business document, it is collaborationdeveloped for an audience of business and technical people. Therefore, technical writing principles apply.

Post Script
“The perfect is the enemy of the good,” is a quote attributed to the French writer and philosopher, Voltaire. With all the guidance on technical writing, it is common for writersto be in what seems to be an endless cycle of tweaking the words. When that happens to you, remember Voltaire. There is a point of diminishing returns.

Author: Mr. Monteleone holds a B.S. in physics and an M.S. in computing science from Texas A&M University. He is certified as a Project Management Professional (PMP®) by the Project Management Institute (PMI®), a Certified Business Analysis Professional (CBAP®) by the International Institute of Business Analysis (IIBA®), a Certified ScrumMaster (CSM) and Certified Scrum Product Owner (CSPO) by the Scrum Alliance, and certified in BPMN by BPMessentials. He holds an Advanced Master’s Certificate in Project Management (GWCPM®) and a Business Analyst Certification (GWCBA®) from George Washington University School of Business. Mark is the President of Monteleone Consulting, LLC and can be contacted via – www.baquickref.com. 

Further Reading

1. Technical Writing references

1. Alred, Gerald, Brusaw, Charles, Oliu, Walter (2011), “Handbook of Technical Writing (10th Edition)”
2. Reep, Diana (2010), “Technical Writing: Principles, Strategies, and Readings (8th Edition)”
3. Pearsall, Thomas, Cook, Kelli (2009), “The Elements of Technical Writing (3rd Edition)”

2. Monteleone, Mark (2012), “Verifying Requirements Documentation,” www.batimes.com