Requirements on the Record
Requirements, Party of One
When I co-founded an aircraft sales listing service in 1995, I wrote a document detailing the requirements and specifications for the website. No one ever looked at the document besides me. So, why take the time in a frantic start-up to draft it? I obsessed over the details of the requirements. By documenting them, I freed myself to move onto many other aspects of the new enterprise.
As a technical leader, I realized keeping requirements in my head created a single point of failure. If I became unavailable to the company, our newborn company would lose essential information, stalling its growth. The document backed up the requirements and specifications for my business partner.
If I started a software company by myself today, I would put requirements, user stories, process maps, and use cases into documents or a knowledge base. Doing so would give me a clearer understanding of those details in writing than in my memory. That alone makes the effort worthwhile, even at the smallest possible scale - one person.
Requirements for All Stakeholders
The article Motivating Specific Requirements discusses capturing what a customer needs in enough detail to develop a valuable software solution. Once a business analyst or architect has the requirement details, s/he should document and organize them to clarify his/her understanding. The requirements details should have enough clarity to enable all stakeholders to achieve a similar level of understanding. These details come in six categories:
A glossary of customer terms
A concept map showing relationships between the terms
A process map showing the steps of a process
A list of business requirements the solution will fulfill
User stories that meet the requirements
Use cases with additional details about user stories
The concept map below shows the relationships between these information categories. Click or tap a concept for more information about it.
An Important “How” Question
Motivating Specific Requirements favors “why, who, what, and when” questions over “how” questions to discover what stakeholders need from a solution. “How” questions lead prematurely to implementation of the solution without fully capturing the breadth and depth of the stakeholders' needs.
Once the stakeholders have answered the “why, who, what and when” questions in sufficient detail, an important “how” question emerges. How does one record and organize the answers to facilitate understanding of the requirements by all stakeholders?
Requirements for Recording Requirements
Recording requirements details requires a means to create and share documents at a bare minimum. Most organizations have at least one way to share documents. All authorized stakeholders should have access to shared requirements documents. For example, an organization may use OneDrive only for internal documents and use Google Docs to share requirements documents.
A drawing tool enables a business analyst or architect to illustrate processes and concepts to other stakeholders. Process and concept maps accelerate understanding of the requirements for all stakeholders through visualization of relationships.
Requirements in the Records
Entering requirements in records rather than documents helps finding and reporting on them as the number of projects, requirements, and user stories grows. Finding one requirement or user story out of hundreds of documents poses a major challenge. Requirements records can have attributes like “Priority,” “Business Impact,” and “Status” to search requirements and create progress reports.
Tying it All Together
Requirements, user stories, and process maps show a summary, with supporting details in separate documents. When presenting a process map for example, a question could arise about a process step. A related document has the answer to the questions. The person presenting the process map should be able to quickly access the document and answer the question.
Business analysts and architects have many solutions available to capture requirements and related details. In the sections below, I highlight a few of the most widely used tools.
Elements.cloud Covers Requirements and More
Elements.cloud focuses on documenting Salesforce orgs, including tools to create and manage requirements, user stories, process maps, and concept maps. The concept diagram above shows these with blue boxes.
Elements.cloud links any of the above to shared documents that have a URL. For example, the glossary and use cases could reside in Microsoft Word documents on Microsoft OneDrive, Box or Dropbox, and link to requirements, user stories, process map, or concept map.
I created the concept map above using Elements.cloud. Its diagramming tool focuses on process mapping and adapts to other purposes such as concept maps and entity-relationship diagrams.
Elements also offers useful tools to document and clean up a Salesforce org, perform impact analysis of changes, and provide feedback and help for custom apps.
See Elements.cloud for more details.
Do More Yourself with Google Workspace
Google Workspace (formerly G Suite) provides general purpose tools to create and share documents and drawings. It includes Google Docs for requirements, user stories, use cases, and a glossary. Google Drawings facilitates creating process and concept maps.
See Google Workspace for more details.
Developer-Friendly Atlassian
Most software developers use Atlassian JIRA to track development of user stories. JIRA supports grouping stories into “epics,” which can represent business requirements. A JIRA expert can configure it to support requirements specifically, as well as customize fields and page layouts. Atlassian has a marketplace with add-ons that support requirements management and drawing diagrams.
Atlassian offers Confluence to create and manage shared documents. It features document collaboration and integration with JIRA. Atlassian works well for those who need flexibility at the cost of complexity.
See Atlassian for more details.
Product Capabilities for Each Information Category
The table below lists the requirements information categories, with columns for Elements.cloud, Google Workspace, and Atlassian JIRA / Confluence. The colored boxes show the level of support each product has for each information category.
| Category | Elements | Atlassian | |
|---|---|---|---|
| Glossary | Linked Doc | Doc | Doc |
| Concept Map | Built-in | Drawing | Add-in |
| Process Map | Built-in | Drawing | Add-in |
| Requirements | Records | Docs | Records |
| User Stories | Records | Docs | Records |
| Use Cases | Linked Docs | Docs | Docs |
Key
Green boxes - product supports the category “out of the box”
Add-in - a drawing app added to Atlassian JIRA or Confluence
Drawing - Google Drawings, usable for process and concept maps
Linked Doc(s) - documents related to Elements process maps, requirements or user stories
Records - requirements records configured in JIRA
Docs - keeping requirements and user stories in documents in Google Docs
Elements, Google and Atlassian Product Integration
The concept diagram below shows relationships between Google Workspace components, Atlassian components, and their relationship with Elements.cloud.
What Do You Use?
If you have favorite tools to capture and illustrate requirements, please leave a comment below with the tool’s name and how it benefits your discovery of client needs. I’ll take a look at it.
Recording requirements and illustrating them with maps clarifies understanding of the requirements for all stakeholders.