Hello my fellow, lemons? I have this problem in my current project I’m out of clue how to approach it. Maybe someone had similar experience and can give an advice.
Our requirements captured in JIRA. Throughout years we accumulated thousands of user stories. Say suppose following naive requirements team knows about:
- Day 1: create home page
- Day 20: create profile page
- Day 50: add green footer to all pages
- Day 100: create admin page Day 150: change footer color to blue
Now I’m doing refactoring (yes, I know, this is the actual problem) on day 400 and noticed that footer on profile page having green footer. Because requirements are just set of individual statements not consolidated with all history of system no one on the team knows why is that, is it bug or requirement did change on day 300 but we cant find it now.
When I worked in Waterfall we had BRD and FRD stating current actual desired state of system which was “reduced” from individual requirements which were coming in throughout project life. When in doubt devs can check FRD and not only know how system expected to behave but also which are other parts of the system that will be affected. How is it in Agile? To my understanding FRD is not a thing in Agile. Do I need to scan through hundreds of tickets and hope I didn’t miss anything every time i’m doing any non-trivial change to system?
I think there are two separate things I want to address here:
First, agile isn’t a project management methodology, it’s just a set of 4 abstract priorities and 12 abstract principles. It’s very short, you can check it out here:
Nothing here says that you’re not allowed to write documentation, write down requirements, etc. In fact, the principles encourage you yourself as a software team to create the exact processes and documentation that you need in order to meet your goals.
“Working software over comprehensive documentation” does not mean you aren’t allowed to have documentation, it just means that you should only write documentation if it helps you build working software, rather than writing documentation for the sake of bureaucracy.
“Individuals and interactions over processes and tools” does not mean that you should have no processes, it just means that the individuals in your team should be empowered to collaboratively create whatever processes you need to deliver good software.
Secondly, in terms of practical advice:
- Talk about this problem with your team. Is it hard for others to figure out where requirements came from? Maybe they already have a good method and can share it with you. If it’s hard for everybody, then propose improvements to your process, for example, propose some type of design document process as part of building any new features
- There are no perfect answers to the question of “how do I safely make non-trivial changes to systems”, but the general approach is to ensure that:
a. You have metrics about how your system is used.
b. You have automated tests covering any requirements, so that you can feel confident when making changes to one part of the system that it isn’t violating any unrelated requirements.
c. You actually document any confusing parts in the code itself using comments. The most important thing to cover in comments is “why is this logic necessary?” - whenever something is confusing, you need to answer this question with a comment. Otherwise, the system becomes very annoying to change later on.
If you are missing any of the above, then propose to your team that you start doing it ASAP
- At the end of the day, somebody is responsible for making product decisions. Is it your team? Or maybe some separate product owner? Sometimes, you just need to communicate with whoever is responsible to figure out if any requirements are still relevant, or if they are now safe to change.
Agile tries to solve this differently.
First and foremost, it puts you into tight-knit communication with your team and the customers, so just ask if anyone remembers why it is like that.
If no one does, then Agile enables to basically fuck around and find out.
Which is to say, change it to how you think it’s supposed to be and see if anything breaks / anyone complains. If that happens, Agile allows you to react quickly, i.e. to change it back and quickly release a fixed version.
But yeah, as the others said, if your team feels like documents work better for them, then do Agile and documents. You’ll know best what process works for your context.
The way I’ve dealt with this before is reference the ticket number in the commit message. Now the only tickets you ever need to review are the ones relevant to the element in question, and only those creating or modifying that particular property, which should be evident in your commit log.
You don’t specify a language but I’d assume that is the footer definition/html and any scripts or styles invoked by it.
But once you have an answer, it would be wise to document it in confluence somewhere, even if it’s something like “Footer green per request from Director, Mr. Smith” or “Footer color: arbitrary, green to differentiate profile pages. Verify changes with Director.”
How to organize the documentation so that it isn’t difficult to navigate is another difficult question that is more art than science - one which has never been satisfactorily solved anywhere I’ve worked once complexity reaches a certain point, but I leave that exercise to the reader.
You can have documents in Agile too
In a way, this question itself is very “un-agile”. Agile should be always forward-looking, “What can we do next?”, “What can we get done in this short period of time?”, “What should we do next?”.
OK, so you found a possible “defect” in your system. Is it a defect, or did someone slide in a requirements change 3 months ago?
This reminds me of playing chess. Sometimes a player will make their move when their opponent is distracted. The opponent hears, “Your turn”, and they look at the board. “Which piece did you move?”. The first player just shrugs.
The point is that you shouldn’t need to know which piece just moved. Every chess position is a “state” of its own, and your best move should depend on going forward from that state, not knowing how the board changed recently.
It’s the same thing here. You have a situation. Does it really matter how, when, who or why it happened? It shouldn’t, and here’s why:
Just because it’s a defect (if it is) doesn’t automatically mean that correcting it moves to the top of your “to do” list.
It’s going to take some non-zero amount of time to change it back to blue. And when you’re doing that, you’re not doing something else. There is always an opportunity cost to doing bug fixes and you shouldn’t treat them in an ad-hoc way. Should you be spending that time, and who gets to decide if you do? It’s not your decision. It’s the PO’s decision to make.
Maybe the PO doesn’t care about the colour. Maybe they do care, but not if it means some other feature gets delayed. Maybe it’s the most important aspect of the whole system, and there’s no way you can launch with it green. So you cancel the current Sprint and start a new one dedicated to fixing this defect! Maybe they regret asking for it to be blue, and now they’re happy that it’s now green.
If it was me, I’d get a quick T-shirt size estimate on the work required to change it back to blue, then put it in the Product Backlog to be reviewed with the PO. Maybe have a quick chat with the PO, or send a memo about it. Maybe the PO will need to check with their SME to see if anyone remembers asking for it to be changed to green. Maybe not. In any event, it either makes its way into a Sprint Backlog or it doesn’t.
Also, if you’re doing Agile right, then your clients are getting constant, hands-on, experience with your system as it is being developed. To go 100 days without some kind of “release” that they can play with and give you feedback is an anti-pattern. If you are giving them the latest version every week or two and after almost three months they haven’t noticed that the footer is green, then it’s probably not important.
On to the actual question. Jira is a potential sand trap of administrative complexity. The answer is usually to keep everything smaller. Smaller features, and smaller Sprints. Smaller teams. A team of 5 or 6, working in one week Sprints, can only do so much per Sprint. If your fundamental unit of work - a story, or a feature, or a ticket - is set to take something like 1/2 day and forms the basis of your Sprint Backlog, then each programmer on the team can do at most 10 SB items (in a perfect world). Depending on the composition of your teams, you’re probably going to have only about 3-4 programmers - which means 30-40 tickets per Sprint Backlog. And that’s a blue-sky number that’s practically impossible in a world with meetings. A team of 5 or 6 is going to complete closer to 20 Sprint Backlog items in 1 week Sprint in the real world.
The point being that 14 Sprints is your 100 days and each Sprint has about 20 easy-to-understand items in it. Whatever your management tools, it’s a failure if you can’t locate those 280 features in a matter of seconds. And it should be easy to eliminate 270 of them as not possible places where the change happened just from the description.
And when those SB items are small, as they should be, it’s not an onerous task to document inside them the requirements that they are supposed to meet.
When you have 1 month Sprints with tickets that take 2 weeks to complete, then everything becomes a nightmare. It becomes a nightmare because it’s virtually impossible to impose some kind of consistent organizational structure internally on free-form stuff that big. But it’s almost trivial to do it with tiny tickets.
And the other thing that happens with big tickets is that there’s tons of stuff that programmers do without thinking about it too much. If you’ve got two weeks to finish something, then there’s a ton of latitude to over-reach and the time estimate was just a wild guess anyways. If you have 3 hours to do something, then you’re going to make sure that what you need to do is clearly laid out - and then you have to stick to it or you won’t get done in time.
Did somebody “fix” the inconsistent footer colour while doing some huge, 2 week, ticket? Good luck finding out. But that’s not going to happen with tiny, well documented tickets.
Someone probably knows the answer. Ask around. This should include either customers or customer advocates. If nobody knows the answer, then do the simplest thing that accomplishes what you need in order to proceed. Sometimes that means doing nothing. If there are multiple ways to accomplish what you need, do the one that leaves you in a more flexible state for future changes. You can bring up your choices or decisions to team members if you need, possibly during a standup or just ad-hoc.
If you aren’t empowered to take one of those steps, then you are in a dysfunctional environment, in that case, collect your salary and keep your head down, and if you are so inclined, try to find a new company or team to join.