CHAPTER ONE

The Problem and the People

This chapter introduces the problem Otahque solves and the people it serves. There is no code yet: first we agree what the application is for.

By the end of the chapter, you will be able to:

• explain the registration problem behind Otahque;
• describe its people, their tasks, and the limits of their access;
• say what the first version includes and what it defers;
• write a business requirement in plain language.

You will produce a short brief covering the problem, people, desired outcome, and first-version scope.

1.1 A place at the workshop

Before we write our first line of Django code, let us meet the people our application will help.

Imagine you are Sam, organizing a small Python workshop. There are twenty places. You publish the details on a community page and share a registration form. Whenever someone fills it in, a new row appears in a spreadsheet.

At first, this seems sufficient. The event page explains the workshop, the form collects responses, and the spreadsheet gives you a list of names.

Then three messages arrive.

“I submitted the form twice. Did you receive it?” asks Sai.

“I cannot make it on Saturday,” Raj tells a volunteer.

“Is there still a place for me?” asks Soni.

Each person has a reasonable question. To answer correctly, you need to know what the registrations look like now, after duplicates and cancellations have been taken into account.

That everyday difficulty is where Otahque begins.

Three tools and one missing answer

The event page, form, and spreadsheet each do a useful job. The difficulty is that a change in one place does not always reach the others.

Sai’s second submission adds another row, but it does not represent another person. Raj’s message changes his plans, but the spreadsheet will not know about it until someone updates it.

Before replying to Soni, you must bring those pieces together.

Suppose the spreadsheet has twenty rows. Two belong to Sai, and one belongs to Raj. If every other row represents a different person who is still attending, there are eighteen attendees, not twenty.

The calculation is simple. The challenge is having the right information when you need it.

Pause and think: if Raj tells only a volunteer, what must happen before you can give Soni an accurate answer?

One change with a clear result

Now imagine that Raj opens his registration and selects Cancel. The application records that change. When the organizer next opens the attendee list, Raj is no longer counted among the people attending.

Raj also sees that his registration is cancelled. Both people can understand the result without exchanging another message.

This is the starting idea for Otahque: a community application where people can find events, register, and manage their participation, while organizers work from an up-to-date record.

The diagram shows the behaviour we want. It does not yet describe servers, databases, or how the code works. We will introduce those ideas when we need them.

We will keep the first version deliberately small. Section 1.3 decides exactly what it includes.

Describe the need before the solution

We can express the problem in two sentences:

Organizers need to know who is registered for their events. Attendees need to know whether they have a place and how to change their plans.

A statement like this helps us decide what the application should do. For example, confirmation is useful because it answers Sai’s question. Cancellation is useful because it lets Raj update his participation.

When we describe an outcome that the product must support, we call it a requirement. For now, ordinary sentences are enough:

• A visitor can read the details of a published event.
• A person who registers can see whether it succeeded.
• An organizer can see the current attendee list.
• A registered attendee can cancel and see the updated result.

As the application grows, we will organize these requirements in a document and connect them to the features we build.

Notice what we have left undecided. We have not chosen a database, designed every screen, or explained registration rules in detail. We still need to decide when registration closes and what should happen if two people request the last place together.

Those questions will guide later lessons. Recording a question is useful progress, even before we know its answer.

Try it yourself

Think of an event you have organized or attended. Choose a moment when someone was unsure what to do.

Write two sentences explaining who was affected and what made their task difficult. Describe the experience before suggesting a feature.

For example: “The event location changed. I could not tell whether my confirmation had the correct address.”

Questions and answers

Que. 1 In our workshop example, why did twenty spreadsheet rows represent only eighteen attendees?

Answer. One row was Sai’s duplicate, and one belonged to Raj, who had cancelled. Removing those two entries leaves eighteen attendees.

Que. 2 After Raj cancels, what should Raj see? What should the organizer see?

Answer. Raj should see that his registration is cancelled. The organizer should see an updated attendee list that no longer counts Raj as attending.

Que. 3 Which describes a need: “Use a blue button” or “Let attendees check whether they are registered”?

Answer. Letting attendees check their registration describes a need. Button colour is a design choice; it does not explain what the person needs to accomplish.

Que. 4 What would a strong answer to the exercise include?

Answer. It names the person affected and the moment of difficulty, then says what they could not tell or do. For example: “Two attendees received different start times. Neither could tell which message was correct.” It describes the experience, not a feature such as a reminder button.

Next: meet Otahque’s users and explore their responsibilities.

1.2 Meet the people

An application can keep its records perfectly and still make life difficult for the people using it. Before choosing screens or writing code, we need to understand what each person is trying to do.

Return to our Python workshop. Soni has heard about it from a friend. She wants to know where it is, when it starts, and whether beginners are welcome. She has not registered yet. At this point, she is a visitor: someone exploring a published event.

Sai has already registered. She wants to check that she has a place. Raj has registered too, but his plans have changed. He needs to cancel his own registration. Both are attendees, although the actions they need are different.

Sam is organizing the workshop. He needs to publish accurate details and see the current attendee list. If the venue changes, he must be able to update the event information.

These descriptions give us three starting roles: visitor, attendee, and organizer. A role describes the part someone plays in a particular situation. It helps us explain what they need to see and what they should be allowed to change.

Start with the task

Instead of asking only “Who uses Otahque?”, ask “What has this person come here to do?” Sai is not looking for a dashboard full of numbers. She wants a clear answer to a small question: am I registered?

One person can play different roles

Sam organizes the Python workshop, but he also wants to attend a photography walk run by another organizer. He is an organizer in the first event and an attendee in the second.

This matters because responsibility has a boundary. Organizing one event should not automatically let Sam edit every event in the community.

We do not need to decide how to store these roles yet. We first need to agree on the behaviour. Later, when we design the data and write Django code, this example will help us judge whether the implementation matches the intended rules.

For now, write the boundary in ordinary language: an organizer may manage the events they are responsible for. An attendee may manage their own participation.

Separate a need from permission

A need tells us what someone wants to accomplish. A permission tells us whether they are allowed to perform a particular action. The two are connected, but they answer different questions.

Raj needs to change his plans. Giving him permission to cancel his own registration supports that need. Giving him permission to cancel Sai’s registration does not.

Likewise, Soni needs to understand the workshop before joining. She should be able to read its published details. That does not mean she needs access to the attendee list or other people’s contact information.

Make the boundary visible

If Raj opens a registration page on a shared computer, how will the application know that the registration belongs to him?

Later, we will introduce signing in and ownership checks. For now, the rule is enough: opening a page must not automatically grant permission to change its records.

What about volunteers?

Raj tells a volunteer that he cannot attend. Helping at the venue does not automatically make that volunteer an organizer inside Otahque.

Our first version will not have a separate volunteer role. Volunteers can pass questions to the organizer. If check-in later requires access to attendee records, we will define its limits first.

Try it yourself

Imagine that Sam is preparing the workshop while Soni is deciding whether to attend. Write one sentence for each person: what do they need to accomplish, and what information would help?

Then add one action each person should not be allowed to perform. Use a specific example rather than saying “they should have limited access”.

Questions and answers

Que. 1 Can Sam be both an organizer and an attendee?

Answer. Yes. He can organize the Python workshop and attend the photography walk. His responsibilities depend on the event.

Que. 2 Raj needs to cancel. Should he be able to change Sai’s registration too?

Answer. No. His need concerns his own participation. He should be able to cancel his registration without gaining control over someone else’s.

Que. 3 Does helping at the venue automatically give a volunteer organizer access?

Answer. No. A real-world responsibility does not automatically grant access in the application. We must first define which tasks require access and to which records.

Que. 4 What could your sentences for Sam and Soni say?

Answer. Sam needs to publish accurate workshop details and see who is currently registered; he should not be able to edit another organizer’s photography walk. Soni needs the date, place, and level of the workshop to decide whether to attend; she should not be able to see who else has registered.

We now have a starting set of people, tasks, and boundaries. Keep these examples nearby: they will help us explain requirements, design screens, and test the behaviour we build.

Next: decide what the first version of Otahque should include.

1.3 The first version

Sam now has a list of ideas for Otahque. People could register for workshops, pay for tickets, join waiting lists, receive reminders, and download certificates. Every idea has a possible use. Building all of them together would make it difficult to finish a working application or understand each part.

We need a boundary around our first version. This boundary is called scope: the work we agree to include, together with the work we deliberately leave for later.

Our starting scope is one community running free events, with people registering individually. The first version should let an organizer publish an event and manage its details, while visitors can read about it and attendees can register, check their status, and cancel.

Finish a useful journey

Imagine that Soni reads the workshop details and chooses to attend. Her registration succeeds, she sees a confirmation, and Sam sees her on the attendee list. Later, Soni cancels and both views reflect the change.

That is a complete journey through the problem we introduced. A page with an attractive Register button would not be enough if the registration disappeared when the page was refreshed.

We will build this journey gradually across the book, checking each addition as we go.

Follow the registration through its changes

Before listing more features, follow a single registration. The figure shows the outcomes our first version must explain to an attendee.

A request is not the same as a confirmed place. If the event is full or registration has closed, the attendee needs an explanation. The organizer’s list must contain only the people currently registered.

The figure describes behaviour, not database tables. We will decide how to represent these outcomes when we design the data.

Choose what belongs in the first version

Include work that is necessary to complete the journey. Visitors need published event details. Attendees need a way to identify themselves and manage their own registrations. Organizers need control over their events and a current attendee list.

We also need rules: one active registration per person for an event, a limit on available places, and a closing point for registration. These rules prevent the confusion that brought us to Otahque.

Leave room for later

Paid tickets can wait because our first events are free. Team registration can wait because each person registers individually. Certificates, recommendations, and a separate volunteer check-in screen can wait because they are not needed to reserve and manage a place.

We will also postpone waiting lists and email reminders. When an event is full, the first version can say so clearly. Confirmation will be visible in the application; email delivery can be added as a later improvement.

Write down the questions that remain

What happens when two people request the last place? Can someone register again after cancelling? When does cancellation close? These questions affect included features, so they need answers before we implement those behaviours.

We will settle the rules explicitly rather than letting accidental code behaviour decide them. For now, separating an open question from a deferred feature helps us plan the next step.

Try it yourself

Sam asks for two additions: prevent duplicate registrations and provide downloadable certificates. Which belongs in our first version? Explain your choice using the workshop problem.

Questions and answers

Que. 1 Why should duplicate prevention come before certificates?

Answer. Duplicate registrations make the attendee count unreliable, which is part of our original problem. Certificates are useful later, but people can complete the registration journey without them.

Que. 2 Is a successful form submission enough to confirm a place?

Answer. No. The application must accept and record the registration under the event’s rules. It must then show the attendee a clear result and update the organizer’s list.

Que. 3 Does postponing a waiting list mean we can ignore a full event?

Answer. No. A full event still needs a clear response. We can refuse new registrations with an explanation before adding a waiting-list feature.

Que. 4 Is the last available place a later feature?

Answer. No. It is a case within the capacity rule we already included. We must decide how it behaves before building that part of registration.

Next: describe our business requirements in plain language.

1.4 Business requirements

Sam wants less confusion before a workshop. Sai wants to know whether she has a place. Raj wants his cancellation to reach the organizer. These needs give Otahque a reason to exist. Our next task is to write them clearly enough that another person can understand what we are trying to achieve.

A business requirement describes an outcome an organization needs. Here, “business” means the work of running the community; it does not imply that the events must make money.

For Otahque, one outcome is straightforward: organizers need a reliable picture of who is currently registered so they can plan an event without reconciling several separate records.

Keep the purpose in view

Compare that outcome with “add a Cancel button”. The button may help Raj, but its presence alone does not prove that the problem is solved. If clicking it leaves him on Sam’s attendee list, the confusion remains.

The outcome helps us judge the feature. We need Raj’s changed plans to be reflected in the record Sam uses. The words on the button, the page layout, and the code will support that purpose.

Writing requirements is therefore part of learning to build software. It gives us a reason for the work and a way to notice when a working screen still fails the people using it.

Connect the outcome to observable behaviour

Requirements become easier to understand when we connect them to an example. Follow Raj’s cancellation through the three levels below.

The middle level describes something the product must do. We call this a functional requirement. The final level gives us an observable example we can later turn into a check.

One example does not prove the whole application is correct. It gives us a starting point. We will add cases such as repeated requests and actions attempted by the wrong person as we define the detailed rules.

Our first business requirements document

A business requirements document, or BRD, records the problem, people, desired outcomes, and scope. Here is our first working draft.

Problem and people

Event details, registrations, and cancellations are spread across separate tools and messages. Organizers must reconcile them manually. Attendees cannot always tell whether their registration or cancellation has been recorded.

Desired outcomes

Organizers can use one current registration record when planning an event. Attendees can establish whether they have a place and manage their participation without relying on a separate message to a volunteer.

Scope and boundaries

The first version serves one community running free events. It supports individual registration, visible confirmation, cancellation, and an organizer’s current attendee list. Paid tickets, team bookings, waiting lists, and certificates are deferred.

Assumptions and open questions

We assume that the difficulty in our workshop example is common; we have not yet gathered evidence. Chapter 2 explains how. Open questions include closing times, registering again after cancellation, and competing requests for the last place.

Make a requirement useful

“The system should be easy” is too vague to guide a decision. Ask what difficulty the person faces and what result would help. For Sai, the useful statement is that she can see whether her registration succeeded.

Avoid inventing a target such as “reduce organizer work by 80 per cent”. We have not measured the current work. If we later set a time-saving target, we will first define what to measure and collect a starting value.

Try it yourself

Write one business outcome for the workshop, then one product behaviour that supports it. Finally, describe what Sam or an attendee would observe when that behaviour works.

Questions and answers

Que. 1 Is “use a blue Cancel button” a business requirement?

Answer. No. It is a design choice. The business outcome concerns reliable participation records; cancellation is one behaviour that supports it.

Que. 2 Why record what we are leaving for later?

Answer. It makes the boundary explicit. A useful idea, such as certificates, should not silently become part of the first version.

Que. 3 Do we need codes such as BR-1 to understand the requirements?

Answer. No. Clear sentences come first. Later, short identifiers can help us refer to an agreed requirement from designs, code tasks, and tests. The identifier is a label, not an explanation.

Que. 4 What could your three sentences say?

Answer. Outcome: Sam can plan the workshop from a list he trusts. Behaviour: an attendee can cancel their own registration, and the list updates. Observation: after Raj cancels, he sees “Cancelled”, and Sam’s list no longer counts him.

Next: put the chapter together and check your readiness.

1.5 Putting it together

We began with a workshop and a question: who is actually attending? Duplicate submissions and a cancellation made a simple spreadsheet count misleading. That problem gave us a reason to build Otahque.

We then met the people involved. Sam organizes the workshop. Sai needs confirmation, Raj needs to cancel, and Soni wants enough information to decide whether to register. Their tasks help us choose what the application should do.

What we have decided

Our first version serves one community running free events, with individual registrations. It should connect event publication, registration, confirmation, cancellation, and the organizer’s current attendee list into one working journey.

People’s responsibilities have boundaries. An attendee manages their own participation. An organizer manages the events they are responsible for. Being an organizer for one event does not grant control over every event.

What we have not decided yet

We still need detailed rules for closing times, registering again after cancellation, and competing requests for the last place. We have not chosen the database design or written Django code.

These are deliberate next steps. Chapter 2 will turn the business needs into product requirements, user stories, and acceptance criteria: clear conditions that describe when a behaviour is correct.

A final workshop exercise

Sam opens registration for a free workshop with twenty places. Sai submits twice. Raj cancels. Soni then asks whether a place is available.

Write a short brief covering the problem, people, desired outcome, and first-version scope. Add one question to resolve before implementation.

Questions and answers

Que. 1 What would a useful problem statement say?

Answer. Separate messages and duplicate submissions make the current attendee count difficult to trust. Attendees also need a clear record of whether they have a place.

Que. 2 What outcome should guide the first version?

Answer. Sam can rely on the current attendee list, while each attendee can check and manage their own participation.

Que. 3 Which question remains open?

Answer. One example is how to handle two people requesting the last place. The rule must prevent the confirmed attendee count from exceeding the event’s capacity.

Que. 4 Are we ready to design database tables?

Answer. We have enough context to discuss the product, but we still need its detailed rules. Those rules will guide the data we store and the checks we implement.

Key terms

Use Table 1.1 to check the words this chapter introduced. Chapter 2 builds on each of them.

Readiness checkpoint: explain Otahque’s purpose, users, scope, and one desired outcome in your own words.

Next: Chapter 2 turns these needs into product requirements, user stories, and acceptance criteria.