🧐 agile monocle S01E05: Have you ever seen good requirements?

But we don't write documentation in agile, right?

So, this fifth episode is about requirements. Which is not, I assure you, a bad word.

Since most of you are probably calling requirements with the more agile term “user story”, let’s call them with their original name: requirements.


  • a thing that is needed or wanted.

  • a thing that is compulsory; a necessary condition.

Things we are requested to do — or that we simply want to do — are the basics of our work, there are plenty of different ways to write them and even more ways in which not to write them.

Now, let’s take a look about a few interesting things about requirements, why they exist, why we have a love/hate relationship with them, and why is that it seems that “we don’t write things down because we are agile”.

Writing things down it’s design work

Documenting is an act of design.

As much as we don’t want to over-engineer our software, we don’t want to over-design our product, so we should over-document what we are going to build.

Back for a bit to the Agile Manifesto.

“Working software over comprehensive documentation.”

This value does not state in absolute terms that in agile we don’t write documentations. It’s obviously put in relative terms.

It should be read as “do not over-document your software and down use documentation as a measure of progress”, because:

“Working software is the primary measure of progress.”

Which, you might have guessed it, it doesn’t mean “we don’t document anything, ever”.

“The most efficient and effective method of conveying information to and within a development team is face-to-face conversation.”

This principle doesn’t mean “we don’t write documentation”.

“Working software is the primary measure of progress.”

This principle doesn’t mean “we don’t write documentation” — but yes, at the third straight sprint where the only thing your team did was writing documentation (true story), I might get upset.

“The best architectures, requirements, and designs emerge from self-organizing teams.”

This one too definitely doesn’t read as “we don’t write documentation”.

Now, you might be familiar with the fact that in agile we like to write user stories, which, I hope you start seeing a pattern, doesn’t mean that we don’t write documentation.

But what these stories should be about?

Have you ever seen a good story?

I want to start out with what I consider a masterclass about why writing down requirements doesn’t work as well as we think, and what to do instead. Just watch it and learn, it’s pure gold.

In the agile world we grew accustomed to this:

As a < type of user >,

I want < some goal >

so that < some reason >

See, there are some inherent reasons why user story can’t work:

  • Most people ignore why the narrative format emerged over time (I beg you to watch that Patton’s class I linked above);

  • Most people ignore that you can write user stories in different ways;

  • Most people write user stories as requirements because it’s easy to put specific solutions to very specific problems after the “I want” and “so that”.

Regarding user stories, it’s by far more important to know the 3C concept that explains the real nature of stories:

  • Conversation: we had a conversation about it and, through a story, we pin down a summary of that conversation, in order to remind ourselves that we had the conversation, and in order to keep the conversations going;

  • Card: we have a place where we wrote something down, it’s not floating in the air;

  • Confirmation: we use the story to reach an agreement about what “done” means (more on “done” later, because I think this is one of the most overlooked aspects of writing things down)

Getting side-tracked on the “want” and “so that” part of the user story by writing down specific solutions to specific problems it’s a very common mistake: so focus more on the 3C and less on the story template you are using.

You can describe the goals you are trying to accomplish using you user’s or your client’s point of view, or you can relax it a bit and focus on the job-to-be done, regardless of who really you are focusing on.

An alternative could be the customer personas becoming only “characters”. Focus more on the why and when, rather than on the who and what. Context matters.

One of the problems with user stories:

“Summed up, the problem with user stories is that it’s too many assumptions and doesn’t acknowledge causality. When a task is put in the format of a user story ( As a [type of user], I want [some action], so that [outcome] ) there’s no room to ask ‘why’ — you’re essentially locked into a particular sequence with no context.”

So if we start describing by motives, anxieties, events, situations it’s more likely that we’ll waste less time trying to define an “ideal who”. If the customer exists only in our head, they are going to buy our product with their imaginary money.

Try telling stories with “When…” instead of “As a user…”.

Have you ever seen real user research?

I don’t. I might not have the longest career in the industry, but I’ve never seen customer personas based off a thorough user research process. I’ve seen a lot of super-fake personas based off brainstorming . I’ve seen a lot of people

A little user research it’s better than no user research. It’s not that hard either, and I think that almost anyone can conduct some basic user research: give it a try, because, honestly, I’m a bit tired of seeing the same four or five customer personas popping up in different companies, projects and workshops, over and over again.

If you get the customer persona wrong the entire premise of your user story will be broken: you are always going to end up building something that doesn’t solve any problem.

You will be “done”, or “Done”, but not “DONE”.

Are you “done”, “Done” or “DONE”?

The three levels of “done-ness” are a wonderful concept I heard a few weeks ago (around minute 5’) and I think it can ultimately help us writing better user stories and requirements: I usually provoke teams with the question “Is it ‘done-done’, or is it just ‘done’?” when the end of an iteration is reached, in order to invite them to reflect if what has been built is going to change someone’s life from the very next day.

But the three levels of “done-ness” are a simple but superior way to tackle this:

  • done (all lowercase) it really means that’s a “ready for demo”, and it’s very often what we mean when we put something into the “done” column of our Kanban or Scrum boards;

  • Done (with capital D) means that the Product Owner and stakeholders are satisfied with the result of a sprint, but more often than not it’s either just box-checking;

  • DONE (all caps) means that what we built it’s really going out in the open and we are actually gaining measurable business value by it.

🧐 Now, try this: pick up the latest user story that has been “done” by you team. Is it “done”, “Done” or “DONE”. In the light of the three levels mentioned above, how could you re-write that user story in order to satisfy the “DONE” condition?

What do you see?

This newsletter is about a monocle, not about a monologue. I want to hear from you so if you want to ask about anything or suggest a topic, you can reply to the newsletter, comment here below, or send a request here. I’d like to make it as much interactive as possible. Don’t make me open a Slack channel.

See you next week, agile monocle episode 6 will be out on Monday, October 19th.

(header image: Glenn Carstens-Peters)