I am new to this forum, I will try to explain the best I can what I am facing. I recently entered a new software development company, and I am the coordinator of a team of Product Owners (POs) who (each of them) are in charge of 5 different products.

The thing is that none of them document anything. The business sends requests on a daily basis and they write each requirement just in a simple JIRA issue, so they are not so easy to understand and cannot be properly documented.

On one hand, I am trying to educate the business regarding these practices (but they are very demanding so I don't think I will have luck on that). On the other hand, and here comes my question: given the rush of daily activities, I don't want to be pushing the POs to document every single request that comes in.

So, when would it be appropriate to formally document requirements? I mean, should we only keep track of requirements when they are long ones, and write daily, short ones is just an issue?

  • 1
    What is the problem you are facing with requirements that are not formally documented? Are the development teams having difficulty? Commented Feb 25, 2018 at 8:59
  • 1
    The Agile Manifesto says, "Working software over comprehensive documentation". Is your software not working? Why do you value requirements tracking?
    – Todd A. Jacobs
    Commented Feb 25, 2018 at 15:41
  • Well, software is working, but the process get messy on some occasions... As soon as I started working here, I met with all Dev Leads to see what could be improved from the POs side, and all of them agreed in that requirements were not clear, that each PO did that in their own way without following any standard way, they just put 2 or 3 sentences in a jira ticket and send that to devs...
    – Tala
    Commented Feb 25, 2018 at 17:34
  • 2
    @Tala That's a lack of communications and coordination, not a lack of "specifications." Even if you had hundreds of lines of specs, that wouldn't solve the central problem you're facing.
    – Todd A. Jacobs
    Commented Feb 25, 2018 at 20:57
  • After reading the two current answers to your question (which are good, and that I upvoted) I feel like you probably need to ask some separate-but-related questions about project roles and communications plans, as well as providing more context about your agility framework and processes. The more I think about it, the more convinced I am that you have an X/Y problem on your hands.
    – Todd A. Jacobs
    Commented Feb 26, 2018 at 0:32

2 Answers 2


Some steps to improve requirements communication

As @ToddA.Jacobs pointed out, Agile values "Working software over comprehensive documentation". So, you need to back off from asking for extensive formal documentation. However, if the dev teams say that the requirements are not clear, that is a real problem. I recommend the following steps:

  1. Ask the POs to follow the recommended user story format like this: As a < type of user >, I want < some goal > so that < some reason >. You can find more details and examples here.
  2. See whether the user stories (also known as Product Backlog Item or PBI) follow the INVEST criteria.
  3. User stories are considered an aid to a good dialog between the dev team and the business stakeholders. Backlog refinement sessions are a good place to have this dialog. This dialog should result in the development of good acceptance tests. These acceptance tests should be captured in the Jira ticket.

P.S: Product Owners should have a vision of what is the business problem they are trying to solve and why this particular solution gives the best ROI (Return on Investment). But the way you describe it, they seem to be serving as a post office to communicate piecemeal information from the business to the dev team. This feels like a more important issue for you to look into.


I hear a couple of things in here. First, a PO is not a rebranded BA from waterfall. The Product Owner owns the health and priority of the backlog, but is not a gatekeeper between the business and the team. Rather, the PO should facilitate more effective communications. If the team is saying that the requirements are bad, that is as much on them as it is on the PO. Either can reach out to the business to get more information. If they are using User Stories, one or two sentences is all they should start with. (Fun fact: the reason that User Stories were originally written on 3x5 cards was because there wasn't enough space to write all of the requirements down, making a direct conversation necessary).

Now, regardless of who has the conversation, documentation traditionally served two purposes: one is to understand the ask, the other is to make it clear how the application behaves after the fact.

Understanding the Need

Many teams find that 1-2 sentence user stories with bullet-point acceptance criteria is enough. Other teams may add some sketches for UI or spreadsheets for financial functions. Really, whatever the team needs, they should ask for - again, they can ask the PO, but a lot of times they need to ask the user. If you want to take it further, I'd suggest looking at options like Behavior-Driven Development, in which the PO, Dev Team, and User can all collaboratively write up scenarios that the new functionality will fulfill.

Documenting the Behavior

In waterfall, you used to just look back at the requirements specs, but in agile there is usually a bunch of different documentation, all used when it is the most appropriate. Automated test cases (like the BDD ones) make create documentation because it not only describes how the application should behave, but when you run them it tells you if it really works that way. Of course, end users probably don't want to look at those, so WIKI's and user manuals are still common.

Making Time

Reading into your question and comment a bit, it sounds like there is a time constraint. It's important to remember that Scrum asks the team to do everything needed to call a backlog item done at once. In other words, documentation, testing, and other non-development work is grouped in with the development. This is intended to be non-negotiable. This keeps the team from building up technical debt. This even includes documentation. If they team doesn't spend the time to update the documentation that they need to keep track of how the system works, soon every new feature will need an impact analysis and extensive design cycles, making it very expensive to add even the smallest feature.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.