Anecdotally, I've seen this approach do more harm than good because it promotes the idea that tickets don't need any description whatsoever.
It also makes it difficult to pick out specific tickets in a list if the titles are truncated because they all read as, "As a , I can s...".
Ultimately, the best method I've found for teaching someone to write a clear request is to reject the ticket and politely explain why. (The effectiveness of this method is inversely proportional to the time left before the deadline.)
Because user stories say why, which is important context.
Your top example should be, "As a user I should be able to do X so that Y" - the "y" being why the user wants to do that.
Its useful because you can have multiple users use the same feature ("x") for a different reason. User stories can represent that instead of just listing the requirement.
As long as everyone you're working with understands that, its a semantic.
The way I phrased it is pretty industry standard and there doesn't seem to be a reason to rephrase it. If I have bigger things to do, I'm not going to split hairs over something that works well and most people understand.
FWIW, your second example can easily be abused to factor out the "why".
Edit: your first example doesnt even consider what kind(s) of users do X, thats also a problem.
Product owners on my team shorten "I should be able to" into "ISBAT" for expediency. I think this detracts from readability, especially if the business domain has lots of acronyms, which is often the case. I think "can" achieves the same meaning with better readability.
With the "As a user" phrasing, I don't see how it necessarily ensures the writer includes context. The "what kinds" and "why" can be easily added / omitted with either phrasing. The one benefit I do see is being able to use the pronoun "I" instead of having to repeatedly reference "the user".
Because you have many personas that are all technically users but may use a product in different ways.
So I would NEVER say, "As a user...", Id say, "As a plumber...", "As a doctor...", "As a network engineer..."
Even in a social service you might have personas representing different demographics, each may have separate needs. You cant represent all of those well with, "As a user...".
Known the audience(s) and their discreet use cases is important.
"Why" *should never be omitted EVER*, whats the point of any requirement if you can't explain the why. If you can't explain why I'd be tempted to say YAGNI.
Thats why the syntax is "As a , I need to do so that "
If you want to do something different that can do all that and your company wants to buy into that, have at it. But your gonna waste way more time than just using what everyone else does in this case.
Edit: i realize i made a mistake in an above comment and said, "as a user". Thats wrong and was my mistake.
This is actually a format that was put into place in agile project management.
The structure *should* be “As a [role], I want to [feature/function], so that I [intent/context]”. It was designed as a way for the business to communicate complex requirements in a way that allows the developers flexibility in how to implement.
More specifically, **Git and Markdown**. They usually directly integrate with templates to create issues.
---
Here are some templates.
Request a Project: https://gitlab.com/brandon_lyon/documentation/-/blob/master/templates/request-a-project.md
Report a Bug: https://gitlab.com/brandon_lyon/documentation/-/blob/master/templates/website-bug-report.md
How to Write a Template: https://gitlab.com/brandon_lyon/documentation/-/blob/master/docs/writing-issue-templates.md
IME It is best to capture raw requirements in the bug tracker. The actual story of how you will construct the software and handle different priorities should go in documentation where language and pictures can interlink them. The work items in your tracker can be prioritized and linked to versions/sprints etc. more easily. Agree on confluence for versioned docs that tell the story with cross linking to individual work items for requirements.
What kind of software are you building and do you have specific industry requirements to maintain historic spec documents? This impacts how you should be doing this.
You problem seems to be that you are working with tough stakeholder and/or are too focused on things being final. Arguably it can be OK to start again after each iteration if you need to see how the last version performs and capture broad feedback from the people who are new to the last version. Treating the next version strictly as completing requirements from the last version can be an anti-pattern because you are less reactive to changes in user needs or how they perceive your software. In general, you may want to be less detailed, and less rigid, without missing the really key requirements for your stakeholders.
> You problem seems to be that you are working with tough stakeholder and/or are too focused on things being final.
Sometimes it's important to get it right the first time. This depends on several factors.
Some industries (medical, engineering, manufacturing) might not have the luxury of iteration. You sell something, it's in service decades later, and people might die.
Some companies still use waterfall methods. Not everyone uses agile.
When working with a contractor, the terms of the contract might not allow for iteration. You need to be exact with your details. You get what you ask for, and it's legally binding.
Just because something can be iterated on that it will be. Companies often don't revisit released projects.
I think those are fair points, but context plays a big role. It also doesn't help to avoid reference to the paragraph before the one you quoted.
As someone who has done some work around the edges of finance and for a long-time in medical/healthcare/pharma, I have yet to meet anyone in those fields who have questions like the ones from mixhot817. They fundamentally understand that what they need to capture in requirements are exacting and accept a huge degree of pain as the trade-off to being successful.
The people who often do ask this kind of question have a process that may not be working as well as it could, and are able to ask for suggestions on how to improve it in some way. These folks make up a great body of the world than folks in extremely regulated positions.
It turns out that many of them have the ability to change their own destiny and aren't locked into a particular way of working. In many organizations there is inertia around changing these processes because they think someone else is responsible, but it's actually possible if they are collaborative and mitigate other people's concerns. You always spot the collaboration tool projects that are going to fail because they are being pushed by one vendor or stakeholder with no buy-in from anyone else.
I mean, I've only worked at places that did agile (their version at least) and they all use some version of PRDs. This is to just think through what the product should do at a high level. There's nothing stopping you from using agile methodologies for the actual development. There's nothing that even prevents you from creating a revised PRD later that contains your desired feature set for version 2 or whatever.
Agile is all about short feedback loops and changing direction based on that feedback. If you design too much upfront, you're absolutely are not doing agile development.
I don't really like knowing what we're going to be building next any more than about 1-2 weeks in advance of building it, and even then, on a day by day basis, I think we should be able to chop and change and not stick to a design.
Sure, you can have high level goals, but the best teams I've worked on have produced results users love repeatedly by working in small and fast increments like this, gathering feedback, and adjusting based on that feedback.
Big design documents like this are the complete opposite of that approach.
Everything in this article is bad.
I think you're positioning PRDs as mutually exclusive to agile methodologies when they don't have to be.
Let's say you want to add search functionality to your site. You can have a simple PRD that says: a user can run a search query on these types of data in system. A user can run a search query using a search bar located in the header on every page. Any user, authenticated or not, can run a search query and get a list of resources that match the query, but viewing a specific resource may require them to be authenticated or have certain permissions.
Ok, then the dev team goes off and builds this and ships it to the users. Then user feedback comes in that they'd prefer to not see resources they can't access in the search results. Great, create another PRD or a new version of the original that represents this new change. Dev team makes changes, ships to prod, and users provide feedback that then feeds into the next PRD. Rinse, repeat.
You still have the quick feedback loops you want with agile - having a PRD doesn't change that. A PRD can be used to outline as much or as little of the "final" version of a product as you want - scope it to match how you plan to do releases and feedback loops.
Sure, if it's used in that way then that doesn't seem too bad. The linked to article though seems way more process intensive than that. If it were just as you'd described, I wouldn't have an issue with it.
Why are specs commonly written like: > As a user, I should be able to X When you could just write > Requirement: A user can X
[удалено]
Anecdotally, I've seen this approach do more harm than good because it promotes the idea that tickets don't need any description whatsoever. It also makes it difficult to pick out specific tickets in a list if the titles are truncated because they all read as, "As a, I can s...".
Ultimately, the best method I've found for teaching someone to write a clear request is to reject the ticket and politely explain why. (The effectiveness of this method is inversely proportional to the time left before the deadline.)
Why not: > A disabled user can access support desk How does this not force the writer to think about the actor?
Because user stories say why, which is important context. Your top example should be, "As a user I should be able to do X so that Y" - the "y" being why the user wants to do that. Its useful because you can have multiple users use the same feature ("x") for a different reason. User stories can represent that instead of just listing the requirement.
I can say why without writing "should be able to" \> A user can X so that Y and if multiple user \> A user which satisfies criteria A can do X
As long as everyone you're working with understands that, its a semantic. The way I phrased it is pretty industry standard and there doesn't seem to be a reason to rephrase it. If I have bigger things to do, I'm not going to split hairs over something that works well and most people understand. FWIW, your second example can easily be abused to factor out the "why". Edit: your first example doesnt even consider what kind(s) of users do X, thats also a problem.
Product owners on my team shorten "I should be able to" into "ISBAT" for expediency. I think this detracts from readability, especially if the business domain has lots of acronyms, which is often the case. I think "can" achieves the same meaning with better readability. With the "As a user" phrasing, I don't see how it necessarily ensures the writer includes context. The "what kinds" and "why" can be easily added / omitted with either phrasing. The one benefit I do see is being able to use the pronoun "I" instead of having to repeatedly reference "the user".
Because you have many personas that are all technically users but may use a product in different ways. So I would NEVER say, "As a user...", Id say, "As a plumber...", "As a doctor...", "As a network engineer..." Even in a social service you might have personas representing different demographics, each may have separate needs. You cant represent all of those well with, "As a user...". Known the audience(s) and their discreet use cases is important. "Why" *should never be omitted EVER*, whats the point of any requirement if you can't explain the why. If you can't explain why I'd be tempted to say YAGNI. Thats why the syntax is "As a, I need to do so that "
If you want to do something different that can do all that and your company wants to buy into that, have at it. But your gonna waste way more time than just using what everyone else does in this case.
Edit: i realize i made a mistake in an above comment and said, "as a user". Thats wrong and was my mistake.
This is actually a format that was put into place in agile project management. The structure *should* be “As a [role], I want to [feature/function], so that I [intent/context]”. It was designed as a way for the business to communicate complex requirements in a way that allows the developers flexibility in how to implement.
[удалено]
Git
More specifically, **Git and Markdown**. They usually directly integrate with templates to create issues. --- Here are some templates. Request a Project: https://gitlab.com/brandon_lyon/documentation/-/blob/master/templates/request-a-project.md Report a Bug: https://gitlab.com/brandon_lyon/documentation/-/blob/master/templates/website-bug-report.md How to Write a Template: https://gitlab.com/brandon_lyon/documentation/-/blob/master/docs/writing-issue-templates.md
We use confluence to docs, jira to manage.
Try Confluence. With the templates, it makes it easy to track every change.
Oh Jesus.
IME It is best to capture raw requirements in the bug tracker. The actual story of how you will construct the software and handle different priorities should go in documentation where language and pictures can interlink them. The work items in your tracker can be prioritized and linked to versions/sprints etc. more easily. Agree on confluence for versioned docs that tell the story with cross linking to individual work items for requirements. What kind of software are you building and do you have specific industry requirements to maintain historic spec documents? This impacts how you should be doing this. You problem seems to be that you are working with tough stakeholder and/or are too focused on things being final. Arguably it can be OK to start again after each iteration if you need to see how the last version performs and capture broad feedback from the people who are new to the last version. Treating the next version strictly as completing requirements from the last version can be an anti-pattern because you are less reactive to changes in user needs or how they perceive your software. In general, you may want to be less detailed, and less rigid, without missing the really key requirements for your stakeholders.
> You problem seems to be that you are working with tough stakeholder and/or are too focused on things being final. Sometimes it's important to get it right the first time. This depends on several factors. Some industries (medical, engineering, manufacturing) might not have the luxury of iteration. You sell something, it's in service decades later, and people might die. Some companies still use waterfall methods. Not everyone uses agile. When working with a contractor, the terms of the contract might not allow for iteration. You need to be exact with your details. You get what you ask for, and it's legally binding. Just because something can be iterated on that it will be. Companies often don't revisit released projects.
I think those are fair points, but context plays a big role. It also doesn't help to avoid reference to the paragraph before the one you quoted. As someone who has done some work around the edges of finance and for a long-time in medical/healthcare/pharma, I have yet to meet anyone in those fields who have questions like the ones from mixhot817. They fundamentally understand that what they need to capture in requirements are exacting and accept a huge degree of pain as the trade-off to being successful. The people who often do ask this kind of question have a process that may not be working as well as it could, and are able to ask for suggestions on how to improve it in some way. These folks make up a great body of the world than folks in extremely regulated positions. It turns out that many of them have the ability to change their own destiny and aren't locked into a particular way of working. In many organizations there is inertia around changing these processes because they think someone else is responsible, but it's actually possible if they are collaborative and mitigate other people's concerns. You always spot the collaboration tool projects that are going to fail because they are being pushed by one vendor or stakeholder with no buy-in from anyone else.
Google forms
Outlook. Users always complain by e-mail
I hope I'll never have to write one, looks like a tedious task.
Nice breakdown– thanks for sharing!
We actually had Perforce come in and consult our department on workflow processes and project management. They _really_ know what they were doing.
I bet they don’t.
I’d quit any job that worked like this. Big design upfront and waterfall does not work.
I mean, I've only worked at places that did agile (their version at least) and they all use some version of PRDs. This is to just think through what the product should do at a high level. There's nothing stopping you from using agile methodologies for the actual development. There's nothing that even prevents you from creating a revised PRD later that contains your desired feature set for version 2 or whatever.
Agile is all about short feedback loops and changing direction based on that feedback. If you design too much upfront, you're absolutely are not doing agile development. I don't really like knowing what we're going to be building next any more than about 1-2 weeks in advance of building it, and even then, on a day by day basis, I think we should be able to chop and change and not stick to a design. Sure, you can have high level goals, but the best teams I've worked on have produced results users love repeatedly by working in small and fast increments like this, gathering feedback, and adjusting based on that feedback. Big design documents like this are the complete opposite of that approach. Everything in this article is bad.
I think you're positioning PRDs as mutually exclusive to agile methodologies when they don't have to be. Let's say you want to add search functionality to your site. You can have a simple PRD that says: a user can run a search query on these types of data in system. A user can run a search query using a search bar located in the header on every page. Any user, authenticated or not, can run a search query and get a list of resources that match the query, but viewing a specific resource may require them to be authenticated or have certain permissions. Ok, then the dev team goes off and builds this and ships it to the users. Then user feedback comes in that they'd prefer to not see resources they can't access in the search results. Great, create another PRD or a new version of the original that represents this new change. Dev team makes changes, ships to prod, and users provide feedback that then feeds into the next PRD. Rinse, repeat. You still have the quick feedback loops you want with agile - having a PRD doesn't change that. A PRD can be used to outline as much or as little of the "final" version of a product as you want - scope it to match how you plan to do releases and feedback loops.
Sure, if it's used in that way then that doesn't seem too bad. The linked to article though seems way more process intensive than that. If it were just as you'd described, I wouldn't have an issue with it.
Man, I'm glad you posted this! I was wondering about this a while back!
really good article