Agile, Scrum and Technical Documentation

Real-world analogy

What is it?

Scrum is a way of working in short cycles called sprints. A team takes work from an ordered backlog and meets briefly each day. At the end it shows the result, then looks at how to work better. Alongside it, good developers write down what future readers need. That means a README to run the project, a short spec before a large change, and API docs from OpenAPI. It also means Architecture Decision Records that capture why a choice was made. The reason is the valuable part, because code shows what you did, not why.

Real-world relevance

A new developer joins and finds that orders use optimistic concurrency. Without a record, they see the extra column and the 409 responses, think it is clutter, and remove it. Two months later support staff overwrite each other's edits. A one-page decision record would have explained the choice and the options rejected. In sprint terms, the same developer who raises a blocker on day one saves the team a missed goal.

Key points

• Sprint and backlog — A sprint is a short, fixed period, often two weeks. The backlog is the ordered list of work, and the team pulls what it can finish into the sprint.
• The Scrum events — The sprint holds four events. Planning picks the work and the goal, and the daily is a short sync to adjust the plan. The review shows the result, and the retrospective asks how to work better.
• What a developer does there — In planning you ask questions and say what is unclear. In the daily you say what blocks you. In the retrospective you suggest one change, not a long complaint.
• User story with acceptance criteria — A story says who wants what and why. Acceptance criteria are short checks that tell you when it works, such as "an expired coupon shows an error".
• Estimates talk about risk — An estimate is a conversation about what is unknown, not a promise. A big gap between two people's numbers shows a hidden assumption worth discussing.
• Definition of Done — The team agrees what done means, for example reviewed, tested, merged and documented. Without it, "done" means different things to different people.
• Raise blockers early — A blocker said on day one costs a conversation. The same blocker said on day eight costs the sprint goal.
• The README gets people running — A new developer should be able to clone, set up and run the app from the README. Test it by asking someone new to follow it.
• Write for six months from now — Use an Architecture Decision Record for big choices: context, decision, alternatives, consequences. Add a short spec before a large change, and generate API docs from OpenAPI.

Code example

# ADR 007: Use optimistic concurrency for order updates

Status: Accepted (2026-11-11)

## Context
Support staff and the customer can edit the same order at the same time.
With last write wins, one edit is lost without any warning.
Conflicts are rare, and an edit takes a few seconds.

## Decision
Add a RowVersion column to the Orders table. EF Core includes it in the
UPDATE condition. On a conflict the API returns 409 and the client
reloads the order.

## Alternatives considered
- Pessimistic locks: rejected. A lock held while a person types blocks
  others, and it stays stuck if the browser closes.
- Last write wins: rejected. It loses edits without telling anyone.

## Consequences
- Good: no locks, so reads and writes stay fast.
- Bad: the client needs a screen that asks the user to reload on 409.
- Bad: tests must cover the conflict path.
- Revisit this if conflicts become frequent.

Line-by-line walkthrough

1. 1. This is a Markdown file, one page. The title has a number and states the decision as a short sentence.
2. 2. Status says whether the decision is proposed, accepted or replaced, and when.
3. 3. Context describes the situation and the problem, with facts about how often conflicts happen.
4. 4. Decision says what we will do, in plain words, in the present tense.
5. 5. Alternatives considered lists the other options and the reason each was rejected. This is the part most records miss.
6. 6. Consequences lists the good and the bad results, and says when to revisit the decision.

Spot the bug

# ADR 008: Use Redis for caching

Status: Accepted

## Decision
We will use Redis.

## Consequences
We need to run a Redis server.

Explain like I'm 5

Fun fact

Hands-on challenge

More resources

• The Scrum Guide (Scrum Guides)
• Architecture decision record (Microsoft Learn)
• ASP.NET Core web API documentation with OpenAPI (Microsoft Learn)