Search for how to write requirements and you get two kinds of answers. The first is a list of adjectives: requirements should be clear, complete, consistent, testable, traceable. True, and useless on the day you have a blank document and a stakeholder who said "we just need it to be easier". The second is a template with headings. Also true, also useless, because the template cannot show you the mistakes you are about to make inside it.
This series does the third thing. It takes one realistic project, a gym chain adding online membership cancellation, and writes every requirements artifact a business analyst produces for it, in order, from the problem statement to the traceability matrix. Each artifact is written twice: first the way it comes out on a first attempt, with every flaw annotated, then properly, with the reasoning for each fix. Each finished artifact is downloadable. By the last part, the series has produced a complete requirements pack for one project, and you have seen how every line in it connects to the lines above and below it.
If you want one part only, the index further down links each one. If you want the method, read on.
The project
FlexWell Gyms runs 40 branches. Members currently cancel by phoning their home branch or by cancelling their bank mandate, which creates failed-payment chases and angry reviews. Cancellations arriving via the bank rather than the gym run at 31% of all cancellations. The business wants online self-serve cancellation with one save offer shown before the member confirms. Retention owns the save offer. Finance needs a clean final-payment calculation. The member portal exists; this flow is being added to it.
Five lines, and already two stakeholders pulling in different directions: the member wants out fast, retention wants one more conversation. That tension runs through every artifact in the series, and watching how each one resolves it is most of what the series teaches. If you have read the use case example, you have met this project; that post is Part 5.
The chain, and why the order matters
Requirements are not a document. They are a chain of justification, and each link answers a different question.
Why are we doing this at all? The problem statement and the business objective. A measurable target, a baseline, a deadline. Everything below has to earn its place against this sentence, and most invented requirements die here because they cannot.
Who needs what from it? Stakeholder requirements. One line per group, in their words, with a source. This is the layer most first attempts skip, and it is the layer that catches the conflict between retention and the member before it reaches the code.
What must the solution do, and how well? Functional requirements state behaviour a tester can observe. Non-functional requirements state the limits: how fast, how available, how secure. They are written in the same document and confused in most of them.
How does the interaction actually go? The use case: one actor, one goal, the main flow and every alternate and exception path. This is where "handle errors gracefully" turns into decisions.
What does it look like? The use case diagram scopes the system. The activity diagram shows the flow with its decisions. The sequence diagram shows which component talks to which, in what order, and what happens when one does not answer.
How will the team build and test it? User stories carry the goal into a backlog; acceptance criteria make each one testable without losing the trace back to the requirement.
What depends on what? The data dictionary and entity diagram name the things the system stores. The traceability matrix is the closing artifact: a table that links every objective to its requirements, every requirement to its use case step, and every step to its test. If a row in that table is empty, something is either unjustified or untested.
The order is the order of justification, not of calendar days. On a real project the middle artifacts are drafted together and corrected against each other; the functional requirements in Part 3 exist partly because writing the use case exposed a frozen-membership case nobody had mentioned. What the order gives you is a question to ask of any line in any document: what above it justifies this, and what below it details this? A line with no answer in either direction is the one to delete or escalate.
Written badly, then well
Every part uses the same format, because it is the format that templates cannot offer. The bad version is not a parody. It is assembled from the patterns that appear in most first attempts, and it looks acceptable at a glance because the headings are right and the sentences are grammatical. The annotations are the point: each one names a specific flaw, explains the damage it does downstream, and is numbered so you can audit your own work against the list afterwards.
The good version follows, with the reasoning for each change, and with the conventions a reviewer would expect: identifiers, sources, rationale, acceptance measures, open questions with owners. Then the finished artifact is available as a formatted document, the way it would land in a requirements pack or a portfolio.
Two things are deliberately kept in. Open questions stay open, with an owner and a note on whether they block anything, because analysis with no unresolved questions was performed on a problem that did not exist. And every decision that ranks one stakeholder's interest above another's is written down where the losing stakeholder can object to it in review rather than in production.
Conventions used throughout
Identifiers are consistent across the whole series, so a reference in Part 8 points at the same thing it pointed at in Part 3.
- BO business objective, the one sentence the project exists for
- SR stakeholder requirement
- FR functional requirement
- NFR non-functional requirement
- BR business rule, a constraint that would exist without any system
- UC use case, with numbered steps and lettered alternate and exception flows
- OQ open question, with an owner
"Shall" is the only word of obligation. "Should" appears nowhere in a requirement, so it cannot creep in as a weaker category. Rules are stated once, with an ID, and referenced; they are never paraphrased inside a requirement.
The parts
Reading order below is the chain described above. Publishing order is different, because the parts with the highest search demand and the strongest links to existing posts came first. Parts not yet published are listed without a link and appear as they go live.
- 1Problem Statement and Business Requirements Coming
- 2Types of Requirements Coming
- 3Functional Requirements
- 4Non-Functional Requirements Coming
- 5Use Case
- 6Use Case Diagram Coming
- 7Activity Diagram Coming
- 8Sequence Diagram Coming
- 9User Stories and Acceptance Criteria Coming
- 10Data Dictionary and ERD Coming
- 11Requirements Traceability Matrix Coming
Start with Part 3, functional requirements, if you want the artifact most projects cannot do without and most first attempts get wrong in the same twelve ways. Start with Part 5, the use case, if you want to see the flow before the requirements that govern it.
What this series is not
It is not a methodology. BABOK, the IIBA's body of knowledge, names these artifacts and these layers, and the series uses its vocabulary because that is the vocabulary hiring managers and senior analysts use. But nothing here depends on certification, and the artifacts work the same way on an agile team that calls functional requirements "stories with acceptance criteria" as on a programme with a 60-page specification.
It is not a template pack. There are no blank templates to download. A completed artifact you can hold next to your own attempt is worth more than a blank one, and the annotated bad version is worth more than either.
It is not a tool tutorial. Diagrams in the series are drawn from text sources with an open-source tool, and the source is shown under each one so you can adapt it, but nobody is grading your diagram software and neither is this series.
Related reading
Two posts outside the numbered series cover what happens before and around it. The requirements you will miss on your first BA project is one elicitation workshop run badly and then well, which is where the stakeholder requirements in Part 1 come from on a real project. Business analyst portfolio examples shows a complete, shorter requirements pack for a different company, with the one-page summary a hiring manager reads first; it also lists five other project briefs you can practise on, and FlexWell is the first of them.
Write your own alongside it
Reading annotated mistakes is not the same as catching them in your own work. The way to use this series is to pick a different project, ideally from a domain you know, and produce each artifact as its part is published, then audit it against that part's annotations before reading the good version. The gap between your attempt and the corrected one is the lesson; the corrected version alone is just another template.
If you want the audit done for you, with a grade and specific feedback on each artifact rather than a checklist, that is what BAvolta's Case Lab is for: you read the stakeholder messages, run the discovery, produce the requirements and the use case, and get structured critique on each one. On Pro, the artifacts export to PDF and land in your portfolio. Module 1 and your first Case Lab case are free. No card needed.
Frequently Asked Questions
What order should requirements artifacts be written in?
Problem statement and business objective first, then stakeholder requirements, then functional and non-functional requirements, then the use case and its diagrams, then user stories with acceptance criteria, and finally the traceability matrix that ties them together. In practice the middle artifacts are drafted together and corrected against each other; the order is about what justifies what, not a strict sequence of days.
Do I need every artifact in this series on a real project?
No. Small changes often need a problem statement, a handful of functional requirements and acceptance criteria. Integrations and anything with failure modes earn a use case and a sequence diagram. The series shows the full set so you can recognise which ones a given project needs and skip the rest deliberately rather than by omission.
Is this series for beginners or experienced business analysts?
Both. Each part shows a first attempt with every flaw annotated, which is what a career switcher needs to see, and then the corrected version with the reasoning, which is where working analysts find the arguments they have been making without the words for them.
Why does the whole series use one fictional company?
Because the value of requirements is in how they connect. A functional requirement is only meaningful next to the stakeholder requirement that justifies it and the use case step that details it. One project makes those links visible across every part; separate examples per artifact would hide them.
Can I use FlexWell in my own portfolio?
Use it to learn the structure, not as your portfolio piece. Every reader of this series has FlexWell. Pick a different domain, ideally one you know from a previous job, and apply the same chain of artifacts to it.