Artifact §01 · Writing sample
One requirement, written out in full
This is a worked example. It is not a client deliverable, and no employer of mine is described in it. I wrote it because requirements experience on a resume is a claim nobody can check, and I would rather hand you something you can read and disagree with.
The starting point is the first line on my homepage. Somebody says they need better reporting. What follows is everything between that sentence and something a developer can build without guessing. The process map and the UAT pack pick the same requirement up from here and carry it to sign off.
What arrived
We need better reporting. Month end is a nightmare and I am tired of chasing numbers.
Financial controller, in a corridor, no ticket, nothing attached
There are two things in that sentence worth noticing. The first is that it names a solution, not a problem. The second is that the real information is in the second half, which most people would treat as venting. Chasing numbers is a process description. It is the only concrete thing said.
What I asked, and why
These are the questions, in the order I would ask them. The order matters. The first three are about what happens today, because people describe their current process accurately and their future one aspirationally.
-
Walk me through your last month end. Start from the morning of the first working day and tell me where you stopped and waited.
Why The request named a tool. This asks for the process. Waiting is where the cost is, and people can always tell you what they waited for.
-
What are you doing right now instead of the report you want?
Why Whatever workaround exists is the truest requirements document in the building. Somebody built it under real constraints and it survived.
-
Which number, specifically, do you not trust?
Why Better is a comparative with no baseline attached. This forces one concrete failure into the open, and it is usually the whole problem.
-
Who reads this after you, and what do they do with it?
Why The downstream reader determines format and timing far more reliably than the requester's own preference does. Ask before someone picks a chart type.
-
What actually happens if it is two days late?
Why This separates a hard external deadline from a strong preference. Both are legitimate. Only one of them should drive a build.
-
If this number came out wrong, who would be the one to say so?
Why It finds the real owner before sign off rather than after go live. It is also less confrontational than asking who is in charge, and it gets a straighter answer.
What changed once they answered
The reporting was fine. Nobody was short of reports. Two systems held the same figure, they disagreed by a small amount every month, and one person spent three days finding the difference by hand before anyone could publish anything. The lateness was a symptom of the reconciliation, and the distrust was a symptom of the lateness.
So the requirement is not a report. It is a reconciliation with a deadline attached, and the report is how you read the result. That distinction is the entire value of asking six questions instead of opening a ticket.
The requirement
- Reference
- FIN-014
- Business owner
- Financial controller
- Delivery owner
- Business systems analyst
- Status
- Drafted, awaiting sign off
- Priority
- High. Blocks the close calendar.
Context
The general ledger and the production ledger record the same month end position and currently disagree. The variance is identified manually, which takes roughly three working days and delays every downstream report. No one downstream can act on a figure until that reconciliation is finished, so the delay is the constraint, not the reporting.
User story
As the financial controller, I want the variance between the general ledger and the production ledger identified for me at line level, so that I can publish a signed month end position by the third working day instead of spending three days locating the difference.
Acceptance criteria
- Given both ledgers have been closed for the period, when the reconciliation is run, then every line where the two ledgers disagree is listed with the account code, both values, and the difference.
- Given a reconciliation has completed, when the controller opens the result, then the total of all listed differences equals the difference between the two ledger totals, with no unexplained residual.
- Given either ledger has not been closed for the period, when a reconciliation is attempted, then it does not run and the controller is told which ledger is still open.
- Given a completed reconciliation, when the controller exports it, then the output is an XLSX file that opens without a conversion prompt and preserves the account codes as text rather than numbers.
- Given the period close calendar, when the second working day ends, then the reconciliation for that period has run at least once without manual intervention.
Out of scope for this release
- Correcting the underlying variance. This release finds it. Fixing the source is a separate piece of work and a separate conversation with the production team.
- Any change to either ledger's own reporting.
- Automated posting of adjustments. The controller has asked to keep that manual and I agree, at least until the variance pattern is understood.
Open items
-
OI-1 Production lead Before build
Do the two ledgers use the same account code set, or is there a mapping nobody has written down? If there is a mapping, this requirement is materially larger.
-
OI-2 Controller Before build
Is there a variance threshold below which a line does not need reporting? Answered no so far, which I want confirmed in writing rather than assumed.
-
OI-3 Controller and audit Before UAT
Does the reconciliation output need to be retained as an audit record, and for how long? This changes storage, not logic, but it is cheaper to know now.
Technical sign off Delivery lead, date
Build starts After both, and not before
What I left out, on purpose
No screen layout. I have an opinion about it and it is not my decision, and putting one in a requirement invites everyone to argue about the wrong thing for a week.
No performance target. I could write that the reconciliation completes in under two minutes and it would look rigorous, but I have not seen the data volumes and I would have written a number I cannot test. A criterion nobody can fail is decoration.
The open items are at the front, not buried in an appendix. A requirement with no open questions on day one usually means nobody has stress tested it yet. I would rather be visibly unfinished in three named places than quietly wrong in ten.
One more thing
Every organisation writes these differently. I have worked with teams who would find this far too formal and teams who would want a traceability matrix bolted to the side of it, and both were right for where they were. I have stopped being precious about my template. If yours is different, I would like to see it, because I have never adopted someone else's format without stealing at least one good idea from it.
Written by Nasmaan Ibrahim for nasmaan.com. Illustrative, not drawn from any employer's systems or data.
Back to the record · 02 The process, drawn · 03 The UAT pack, in miniature · The first fifteen minutes · Resume, PDF