Software projects run on documents, and every one of them looks like an acronym you were supposed to already know. BRD. HLD. RTM. RCA.
They are far less intimidating once you see the pattern. Each document answers one question, for one audience, at one stage of the work. Learn the map and you will know roughly what is inside a file before you open it.
Learning Objectives
After this lesson, you will be able to:
Place the common documents onto the stage of work they belong to
Ask the three questions that tell you whether any document is worth reading
Tell functional and non-functional requirements apart, and explain why the second kind gets forgotten
Write a bug report that a developer can act on without asking you anything
The names below vary between companies. Some places call it an FRD, some an FSD, some just "the spec". The questions those documents answer do not vary, so when the name is unfamiliar, ask what decision it supports and you will usually work out what it is.
The third question matters more than beginners expect. A document that is out of date is worse than no document, because people trust it.
Documents cluster by stage. You will rarely meet all of these in one company, and Agile teams replace several with tickets, but the shape holds.
Which documents belong to which stage
🧭🧭
PlanningBusiness Case, Charter
1
📋📋
RequirementsBRD, FRD, SRS, stories
2
📐📐
DesignHLD, LLD, ADR
3
⌨️⌨️
BuildREADME, API docs, DoD
4
🧪🧪
TestTest Plan, cases, RTM, bugs
5
🚀🚀
ReleaseRelease Notes, Rollback, UAT
6
🔧🔧
OperateRunbook, RCA
7
Planning
Document
Answers
Usually written by
Business Case or Project Charter
Why do this at all? What does it cost, what is the benefit, who sponsors it
Sponsor or project manager
Requirements
Document
Answers
Usually written by
BRD, Business Requirements Document
What does the business need, in business language
Business analyst with stakeholders
FRD or FSD, Functional Requirements
What must the system do, feature by feature: screens, rules, validations
Business analyst
SRS, Software Requirements Specification
The formal complete specification, functional and non-functional together
Business analyst or systems analyst
User stories with acceptance criteria
The Agile-native equivalent, living in a ticket tool rather than a document
Product owner and team
Design
Document
Answers
Usually written by
HLD, High-Level Design
The architecture: components, integrations, tech stack, how data flows
Architect
LLD, Low-Level Design
The detail per module: classes, APIs, database schema, algorithms
Tech lead or senior developers
ADR, Architecture Decision Record
One page per significant decision: the context, the options, the choice, the consequences
Engineers
Development and testing
Document
Answers
Usually written by
README and API docs
How to run, build and call the software
Developers
Definition of Ready and Definition of Done
When can a piece of work start, and when is it genuinely finished
The team
Test Plan or Test Strategy
What will be tested, how, in which environments, and what must be true to start and stop
QA lead
Test cases, linked by an RTM
The step-by-step checks, traced back to the requirement each one covers
QA engineers
Bug reports
What broke, and everything needed to reproduce it
Anyone, most often QA
Release and operations
Document
Answers
Usually written by
Release Notes
What changed in this version, for users and support
Product or dev team
Deployment and Rollback Plan
The exact steps to release, and the exact steps to undo it
DevOps or release manager
UAT Sign-off
The business formally accepting the software
Business stakeholders
Runbook or SOP
How to operate the system: restarts, common fixes, who to call
DevOps and support
RCA, Root Cause Analysis
What went wrong in an outage, why, and what will stop it recurring
Whoever was on call, with the team
What Do You Think?
Your team is choosing between two databases. The decision will shape the system for years, and in eighteen months someone will ask why it was made. Which document is designed for exactly this?
Which document answers this question?Interactive
Eight questions people genuinely ask at work. Match each to the document that answers it — that direction is the useful one, because every document exists to answer exactly one question.
This distinction is worth more than its share of attention, because the second half is where projects quietly fail.
A functional requirement says what the system does. The user can reset their password. An order can be cancelled within thirty minutes. An administrator can export a report.
A non-functional requirement says how well it must do it. The page loads in under two seconds. The system stays available 99.9% of the time. Data is encrypted at rest. The interface is usable with a screen reader. The service handles ten thousand concurrent users.
This is the one document a new joiner writes immediately, and it is a reliable way to build a reputation quickly.
A developer receiving a bug report needs to reproduce the problem. Everything useful in a bug report serves that.
Title. One line, specific. "Checkout fails" is not useful. "Checkout returns 500 when the discount code is expired" tells the reader whether it is theirs before they open it.
Steps to reproduce. Numbered, from a known starting point, with the actual data used. The test of a good set of steps is whether someone who has never seen the bug can follow them and see it.
Expected and actual. State both. "It doesn't work" leaves the developer guessing what you thought should happen, and sometimes the answer is that the software is right and the expectation was wrong.
Environment. Which build, which browser or device, which environment. A bug that only appears in one place is a strong clue, and that clue is lost if nobody records where it appeared.
Evidence. A screenshot, a screen recording, the error text, the relevant log lines. Paste error text as text rather than as a picture of text, so it can be searched.
Severity and priority. These are two different things and are constantly confused. Severity is how badly it breaks the system. Priority is how soon it should be fixed. A typo on the homepage is low severity and can be high priority. A crash in a feature nobody uses yet is high severity and low priority.
Quick Check1 / 3
A cosmetic typo appears in the company name on the public landing page. What is its severity and priority?
Documents scatter. Requirements sit in one tool, designs in another, tickets in a third, and the actual current answer is often in a chat message nobody can find.
Most companies land somewhere on a spectrum. At one end, everything lives in a formal document repository with version numbers and approvals, which is common in regulated industries where an auditor may need to see the trail. At the other end, almost everything lives in tickets and a wiki, with documents written only when a decision needs to outlive the ticket.
Neither is wrong. What causes trouble is not knowing which one your team is, and so looking for a specification that was never written or ignoring one that was.
Every document answers one question for one audience at one stage. Learn the question and the acronym stops mattering.
Ask three things of any document: who is it for, what decision does it enable, and is it current.
Functional requirements say what the system does; non-functional say how well. The second kind shapes the architecture and is the kind that gets forgotten.
A bug report earns its keep by letting someone else reproduce the problem without asking you a single follow-up question.
Severity is how badly it breaks. Priority is how soon to fix. They are independent.
Next: From Idea to Product — how a vague idea becomes a proof of concept, then a prototype, then a minimum viable product, and what each of those words actually means when someone uses it in a meeting.