I've just started in a new company that has decided to become more agile. They have decided to create the requirement specification in Jira. As an ux/ interaction designer, I find it difficult to see the big picture when seeing the list of Epics and tasks in Jira.

I'm used to have requirements per page and per function as it sets the requirements in a context.

1) How should I structure a sort of Agile requirement specification in Confluence?

2) Can an Epic be e.g. Start Page or Profile Page?

2 Answers 2


This is difficult to answer. At a glance, you're asking the kind of question that would make an agile practitioner wince. Your reasoning also reads as if you're prioritizing your personal ("the few") comfort higher than the team's ("the many") success.

Setting that aside, some questions.

When you say "they have decided", who is they? Management? The development team? What's the role of these requirements in your project? When are they written relative to the rest of the project cycle, who writes and maintains them, and who is their audience? Where does the audience tend to work from?

If the team made this decision, shutting it down unilaterally means you are not agile, please gather your things. If management made this decision, start by talking to your team.

If you're defining full requirements up front (this is the part that tends to cause wincing), then the most critical audience is the development team, and they hopefully start at JIRA or some other task-oriented tool (friends don't let friends use Confluence as a task manager).

In this case, the document layout matters a lot less than keeping the contents linked to the JIRA tasks for implementation. If your team is using stories, each story in JIRA should be a hub and a home page for all of the information your team needs to build it from start to finish. If your team knows they can start from the story and find a clear path to the Confluence page, it doesn't really matter where that page is.

If you're interested in some documentation layout ideas, and you're using things like stories and epics, consider looking into user story mapping for a two-dimensional way of looking at the bigger picture and forming a documentation scheme from that. It plays very nicely with Initiative > Epic > Story hierarchy along with free-form Theme tagging (in case you ever buy into Atlassian's Portfolio product). This sort of hierarchy + tags scheme maps to a Confluence page tree + page labels approach quite painlessly.

It also aligns with JIRA and Confluence's native prescription. Confluence's out-of-the-box requirement templates behave like Epic pages with Story tables, and JIRA Agile's Epic management has Confluence page linking plastered all over it. Atlassian wants you to make Epics the smallest unit of 'page' in Confluence, so go for it.

Just try to remember that requirements up front are themselves very much a product, and like a product they have their own requirements and customers who have a say. Make sure whoever will actually be using your requirements has an active role in deciding how they'll be delivered.

  • Thanks @wandering-npc. What I'm trying to get at is; How can user stories be put into context? How can a front end designer / front end developer know what kind of functions / informaton should be per page?
    – Steven
    Commented Aug 19, 2016 at 6:52

Remember that the Agile approach is focused on responding to change.

To achieve this it is useful to not commit early to detailed, written requirements. That is where the concept of user stories came from. A user story is not a detailed requirement, instead it is an invitation to a conversation. It is the conversation that communicates the details.

Now, as you point out, this approach can make it difficult to view the big picture. So my suggestion would be to have just enough detail in Confluence to give your team an overview of the design. What 'just enough' is will vary from team to team and from project to project. Try and find a happy medium between lots of detail and lots of flexibility.

Can an epic be a start page or profile page? User stories and epics are there primarily for the benefit of the Product Owner and stakeholders. They are focused on explaining to the non-technical what is going to be delivered, rather than being an aid to implementation.

So the answer to your question is an epic can be a start page or profile page if that approach is useful to the Product Owner and stakeholders as well as to the development team. I can certainly remember projects where this was true, but it won't be true all the time.

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.