From Requirements to Diagrams: Which Question Does Each Diagram Answer?

Version note: The diagrams in this post use UML 2.5.1 notation; the C# examples were tested with .NET 10.

Guess First

The first requirements text sent by the HR (Human Resources) directorate contains this sentence: "Leave longer than 3 days goes to the director for approval." Two developers turn the sentence into code separately. Ada asks for leave starting on a Friday and ending on a Tuesday. Which of the two lines below is right; will the director see this request?

DateOnly start = new(2026, 11, 27);   // Friday
DateOnly end = new(2026, 12, 1);      // Tuesday

int calendarDays = end.DayNumber - start.DayNumber + 1;
int workingDays = CountWorkingDays(start, end);

Console.WriteLine($"Calendar days: {calendarDays}, needs director: {calendarDays > 3}");
Console.WriteLine($"Working days:  {workingDays}, needs director: {workingDays > 3}");

static int CountWorkingDays(DateOnly start, DateOnly end)
{
    int count = 0;
    for (DateOnly day = start; day <= end; day = day.AddDays(1))
    {
        if (day.DayOfWeek is not (DayOfWeek.Saturday or DayOfWeek.Sunday))
            count++;
    }
    return count;
}

The Word "Day" Produced Two Different Programs

Calendar days: 5, needs director: True
Working days:  3, needs director: False

Both are faithful to the sentence. The developer counting calendar days sends the request to the director, the one counting working days does not. The code cannot tell which is right; only the person who wrote the sentence can. In our case we asked the HR directorate, the answer was "working days", and that is how it went into version 1.0 of the text.

Who asked the question, and when? While extracting a model from the requirements. When you read the text and try to draw a LeaveRequest class with "how many days it lasts" on it, you have to give the attribute a name and a type: calendarDays or workingDays? An ambiguity that plain text glosses over comfortably demands a decision in a model. This is the least discussed benefit of modeling: the diagram you draw confronts you with the questions you do not know the answers to. In this post we write the requirements of the Leave Request module, extract a model from them systematically and match each question with the diagram that answers it. Gathering requirements itself (elicitation, interviews, writing user stories) is the subject of the upcoming Requirements Analysis series; here the text is already in hand.

The Case: Requirements of the Leave Request Module

The HR Portal is the fictional HR software we also use in the Solution Patterns series. Throughout this series we model its leave module. The text approved by the HR directorate is below. The R at the start of each item stands for requirement; throughout the series we will refer to a rule as "R7".

• R1. An employee creates a leave request in the portal: leave type, start and end date, optional reason. The request can first be saved as a draft; the employee submits it when ready.
• R2. On submission the system calculates how many working days the request covers. Weekends and public holidays defined by HR are not counted. Leave types: Annual Leave, Excuse Leave, Sick Leave, Unpaid Leave.
• R3. For annual leave, a request cannot be submitted if the employee's remaining balance for that year is less than the requested working days.
• R4. An employee cannot have two active (not cancelled, not rejected) requests with overlapping dates.
• R5. A medical report file (PDF) can be attached to a sick leave request.
• R6. A submitted request goes to the employee's line manager for approval. The manager approves or rejects it; a reason is mandatory when rejecting.
• R7. Requests longer than 3 working days go, after the manager's approval, to the director of the employee's department. The director also approves or rejects with a reason.
• R8. The balance is checked again at approval time (another leave may have been approved since submission).
• R9. With the final approval the request becomes "Approved"; for annual leave the working days are deducted from the balance and the leave is written to the corporate calendar system.
• R10. On every status change the requester gets an e-mail; for pending requests the approver does too. If the approver does not decide within 2 working days, a reminder is sent to them.
• R11. An employee can always cancel a pending request. An approved request can be cancelled by the employee only before the leave starts; the deducted days are then refunded and the calendar entry is removed. After the leave has started only an HR specialist can cancel it.
• R12. An HR specialist defines leave types and public holidays, views employee balances and can correct them with a written reason.

An ordinary text: twelve items, not even two pages. Yet it contains five different people or systems, four leave types, six states, two approval steps, a timeout and an external system. Let us pull them out one by one.

From Nouns to Candidate Classes

The oldest systematic way to get classes out of text is to look at the grammar. Russell Abbott's 1983 paper "Program Design by Informal English Descriptions" in Communications of the ACM (Association for Computing Machinery) proposed that nouns in plain text correspond to types and objects and verbs to operations. Craig Larman's book "Applying UML and Patterns" describes the technique as "noun phrase identification" and warns right away: there is no mechanical mapping from noun to class, natural language is ambiguous and the same concept appears under different words. It is a starting point, not an answer.

Collecting the nouns in R1–R12 gives a long list: employee, portal, leave request, leave type, date, reason, draft, system, working day, weekend, public holiday, balance, year, report file, manager, approval, reason for rejection, director, department, calendar system, e-mail, reminder, HR specialist. We filter it with these questions:

Does it have its own identity and lifecycle? A balance looks like a number, but "Ada's 2026 annual leave balance" is a thing of its own: it has a year, entitled days and used days, and HR can correct it with a reason. So LeaveBalance is a class. The same goes for approval: who approved, when, at which step, with which comment; these give birth to the Approval class.

Is it a property of something else? Start date, end date, reason and rejection reason do not live on their own; they are attributes of the request or the approval. "Draft" is not a class but a state of the request. "Year" is an attribute of the balance.

Is it vague, or the system itself? "Portal" and "system" are the name of what we are modeling, not a concept inside it. "E-mail" and "reminder" are the outcome of a behavior; we do not make them classes in the first cut.

Is it another name for the same concept? The text says "request", "leave request" and sometimes just "leave". The word "leave" points at two different things: what the employee asks for (the request) and the leave period actually taken once approved. In this module we keep both in a single LeaveRequest class, but that is a decision and it belongs in a glossary. Picking one word per concept and using it everywhere is the core of the "ubiquitous language" idea we will discuss in the upcoming Domain-Driven Design series.

What remains: Employee, Department, LeaveType, LeaveRequest, LeaveBalance, Approval, PublicHoliday and, for the report file, LeaveAttachment. Employee, manager and director are not separate classes; they are all Employee, only their roles towards a request differ. This distinction matters in the next post: in the use case diagram Employee and Manager are separate actors, because an actor represents a role, not a database record.

Turning this first cut into code right away is the fastest way to see what is missing. Above each type I noted the requirement it came from:

Employee ada = new(1001, "E-1001", "Ada Lovelace", ManagerId: 420, DepartmentId: 10);
LeaveType annual = new("ANNUAL", "Annual Leave", DeductsFromBalance: true);
LeaveBalance balance = new(ada.Id, annual.Code, Year: 2026, EntitledDays: 14, UsedDays: 6);
LeaveRequest request = new(42, ada.Id, annual.Code, new DateOnly(2026, 12, 21), new DateOnly(2026, 12, 25), WorkingDays: 5);

Console.WriteLine($"Remaining: {balance.RemainingDays}, requested: {request.WorkingDays}");
Console.WriteLine($"Enough balance (R3): {balance.RemainingDays >= request.WorkingDays}");
Console.WriteLine($"Needs director (R7): {request.RequiresDirectorApproval}");

// R1, R6, R7: the employee, their manager and department
public sealed record Employee(int Id, string EmployeeNumber, string FullName, int? ManagerId, int DepartmentId);

// R2: leave type; only annual leave is deducted from the balance
public sealed record LeaveType(string Code, string Name, bool DeductsFromBalance);

// R3, R9, R12: yearly balance; remaining days are computed, not stored
public sealed record LeaveBalance(int EmployeeId, string LeaveTypeCode, int Year, int EntitledDays, int UsedDays)
{
    public int RemainingDays => EntitledDays - UsedDays;
}

// R1, R2, R7: the request; the threshold is the "3 working days" of the requirement
public sealed record LeaveRequest(int Id, int EmployeeId, string LeaveTypeCode, DateOnly Start, DateOnly End, int WorkingDays)
{
    public const int DirectorApprovalThreshold = 3;
    public bool RequiresDirectorApproval => WorkingDays > DirectorApprovalThreshold;
}

Remaining: 8, requested: 5
Enough balance (R3): True
Needs director (R7): True

Ada's request for 21–25 December is 5 working days; with a balance of 8 it can be submitted, and since it exceeds 3 it goes to director Grace Hopper. This code is deliberately rough: there is no Status, no Approval, only immutable records. The goal of the first cut is to find the right concepts and the right names; responsibilities, states and relationships come in the following posts, with diagrams. But we have already gained something: the constant DirectorApprovalThreshold tells in one line where the "3" of the requirement lives in the code.

From Verbs to Use Cases and Operations

Verbs go to two different places, and the question "who performs the verb?" decides which.

If a person or an external system performs the verb for its own goal, it is a candidate use case: the employee requests leave, the manager decides on the request, the employee cancels the request, the HR specialist corrects a balance. By Alistair Cockburn's yardstick a good use case is a goal the actor can complete in one sitting and then say "I'm done" (user goal level). "Pick a date" or "press Save" is below that level; "manage leave processes" is above it.

If the system itself performs the verb, it is a candidate operation or service responsibility: "the system calculates the working days" points at an IWorkingDayCalculator, "is deducted from the balance" at LeaveBalance.Deduct(), "is written to the calendar" at an ICalendarGateway that talks to the external system. Passive sentences ("is deducted", "is written", "is sent") are the clue here: they do not say who does the work, and giving that responsibility to a class is your job.

"If", "After", "Only Before": Traces of Behavior

The third kind of clue in the text is words that express conditions and time. These do not fit in a class diagram; they go to behavior diagrams.

Conditions become guards. "Requests longer than 3 working days" is the condition of a transition or a decision point: [workingDays > 3]. "Cannot be submitted if the remaining balance is less" is a precondition or a refused transition.

Adjectives describing a state become states. "Pending", "approved", "not cancelled, not rejected" tell you the request has a lifecycle. If the text uses this many state adjectives for one object, that object deserves a state machine diagram. R11's "an approved request can be cancelled only before the leave starts" contains a state (Approved) and a guard ([today < period.start]) at the same time.

Ordering words ("first", "after", "at approval time") point to an activity or sequence diagram. R7 describes a workflow: first the manager, then, conditionally, the director. Which role performs which step goes into the swimlanes of an activity diagram; which object calls which goes into a sequence diagram.

Duration phrases ("if the approver does not decide within 2 working days") are events triggered by time. You will meet them as a time event in a state machine, a timing constraint in a sequence diagram and a background job in code.

Which Question Does Each Diagram Answer?

The question to ask before drawing is not "which diagram should I draw?" but "which question do I want to answer?". For the leave module the mapping between questions and diagrams is:

Each row of the table corresponds to one or two posts of this series. Some questions can be answered by more than one diagram; you can draw the approval flow as an activity or as a sequence diagram. The audience decides.

Who Are We Drawing For? Audience and Level of Detail

You draw the same LeaveRequest at three levels of detail for three different people. When validating requirements with the HR directorate, a use case diagram and an activity diagram with plain-language steps are enough; type names, visibility markers and technical details like DateOnly are noise there. When discussing design within the team, class, sequence and state machine diagrams are drawn with real class and method names, because the conversation turns directly into code. When talking to the operations team, deployment and C4 diagrams contain no classes; they contain containers, ports, protocols and environments.

Inside the class diagram itself there are three levels too: conceptual (only concept names and relationships), analysis (attributes added, types rough) and design (types, visibility, operation signatures, interfaces). The C# code above sits somewhere between conceptual and analysis. We will cover the analysis versus design distinction at the end of the class diagram posts by putting the two levels of the same case side by side.

There is a practical test for choosing the level of detail: if the person you show the diagram to points at an element and asks "what is this?", and the answer is of no use to them, the element does not belong in that diagram.

The Map of the Series

Put the table and the levels of detail together and the path of the series appears. We start from the requirements, pass through three groups of questions and end up at working code:

Each box carries information to the next. Use cases feed the scenarios of the sequence diagrams, the class diagram feeds the types of the lifelines, the state machine diagram feeds switch expressions and unit test scenarios, deployment and C4 diagrams feed the docker compose file. In the last post we will walk through the same module end to end once more and watch which diagrams change when a new requirement such as "half-day leave" arrives.

Common Pitfalls

Making every noun a class. A model that turns "portal", "system", "information" and "date" into classes both grows and loses meaning. Nouns without identity and lifecycle are attributes; vague nouns are dropped from the text.

Mistaking a role for a class. Manager and director are not separate classes; they are roles of the same Employee towards a request. Building a Manager : Employee inheritance collapses as soon as a manager reports to another manager or a director opens their own leave request.

Carrying ambiguity into the diagram. Writing "3 days" into the diagram verbatim does not solve the question, it only postpones it. Every phrase that does not turn into a name and a type in the model is a question for the owner of the text; collect those questions in a list.

Drawing everything. A team that draws a diagram for every sentence in the requirements does not know a month later which one is current. A diagram lives as long as the question it answers keeps being asked; a diagram nobody asks about goes stale and starts giving wrong information.

Not writing the question down. If a diagram is titled "Leave Module", nobody knows what it answers. A title like "Which objects are called in what order when a request is approved?" also tells the diagram's scope and when it will go out of date.

A Small Experiment

★☆☆ Color R10 (notifications and the 2-working-day reminder) as nouns, verbs and conditions. Which nouns deserve to be classes and which are attributes? Compare the result with the candidate classes in this post.

★★☆ Add the public holidays of R2 to CountWorkingDays from Guess First: let it take a holiday list of type IReadOnlySet<DateOnly>. In 2026, 29 October is a Thursday; how many working days does a request from 28 October to 2 November cover? Does the result change the director approval?

★★★ Take a requirements text or issue description from your own project and produce a list of candidate classes using the four questions of this post. How many ambiguities did you find that you need to ask the owner about? Split them into two lists, "decisions" and "questions".

The next post starts with the use case diagram: actor, system boundary, use case and the most frequently confused pair, <<include>> and <<extend>>. We will see that the diagram says little on its own and write the "Request Leave" use case with Cockburn's fully dressed template.