How To Use Confluence To Write Awesome User Stories

I was recently interviewed for a Product Owner role and asked to provide an example of the work I’ve been doing on my side hustle, The response I got was “this is pretty good work” which I interpreted as “you should write a blog about it to help other Product Owners and Product Managers.” A side note, is on hold as I’m currently working, blogging and looking for a new role. You can find a PDF version of the Confluence document here.


For those who aren’t familiar with Confluence, it’s a tool created by Atlassian for the purpose of documentation. It’s widely used in the software development space for writing User Stories and acceptance criteria. The Confluence page below is a modification of one of the templates that comes with Confluence. I modified it slightly to suit the needs of my project. Below the image is a walk through of each part of the page and the reasoning behind why it’s there.

Heading: The heading of each one of my User Stories starts with the name of the Epic it’s associated with i.e. Page Visits. It’s one of the fail safe’s I use to make sure the right Issue is associated with the right User Stories. Following that is the name of the actual feature that is being built. Here, “how long before the first popup displays?” is the front-end of the design. The name is exactly the same as the front-end. I make sure that the headings are unambiguous e.g. “popup display timing” this can be confusing, not to mention there are other features that relate to popup timing. Further to the naming convention, the Issue in my Jira instance has exactly the same name and is linked to the Confluence page. With everything being named the same there is less chance of information getting lost misplaced or meandering through Jira and Confluence to find what I’m looking for. 

Target Release: This would typically be filled in once I have a solid cadence and velocity for my Sprints. At this early stage in the build cycle it is somewhat difficult to predict. Typically, this information would be filled in once the business strategy has been analysed and turned into a Product Roadmap and the Product Road Map chunked down into years, quarters and release dates. As my project is brand new and I don’t have a strategy, I’ll be using a bottom up approach once I have more historical data from the Jira reports.

Epic and Flowchart: is an awesome free online app that allows you to create wireframes… think Microsoft Visio but online and free. I’ve been using it for years and it has served me very well. It integrates with Google Drive, OneDrive, Confluence and Jira. It has a 4 out of 4 star rating from 694 ratings in the Atlassian marketplace which is an indication of how much people like it. If you look at the next row down, Flowchart, you’ll notice a link which goes to a wireframe of the product being designed. If you notice a little further down, there is a screen capture of part of the wireframe that relates directly to this part of the project. The wireframe document is the authoritative document for the whole project and includes wireframes of direct competitors to see how better to build and where a unique value proposition can be obtained. All of this preliminary work is broken down into Epics. Here, you can see the Page Visits Theme and the Reports, User Story and Create & Edit Epics underneath. The wireframe flowchart will also be used for CX, marketing, troubleshooting, on-boarding and road mapping.

Document Status: This is a default feature from the original Confluence template. As the Issue is moved from the Product Backlog, to Sprint Planing and into the Sprint, this is changed from draft, to in progress, to complete.

Document Owner: As I’m in the role of Product Owner for this project and managing a developer, I’m responsible for creating the Jira Issues, Confluence pages, linking them together and completing them so the developer is able to code the outcome with as little interruption as possible. A happy developer is a happy team.

Designer: I currently don’t have a UX/UI designer however this problem is resolved in “GoGo theme link” section below.

Tech Lead: The Developer’s account is added here so we know who is responsible for the work to be completed. In addition, because his name is added to the document, he is notified of all edits to this document and can respond accordingly and in a timely manner. This saves emails back and forth or notifying him in chat then losing the context as the chat progresses.

QA:  Ideally, a Scrum team would have a separate tester in this role however when you’re bootstrapping, that role usually falls to the Product Owner, the Developer, some good requirement documentation and Definition of Done.

Jira Issue: As mentioned above, the Issue in Jira has exactly the same name as the page in Confluence and linked in this section. I only use Jira for the creation and organisation of  Epics, the Product Backlog, Sprint Backlog, Current Sprint, Issues, Reporting and linking to Confluence documents. I don’t use it for chat communication or storing information within the Issues themselves. Use the right tool for the right job to drive efficiency and productivity.

GoGo Theme Link: As I’m not a designer and I’m bootstrapping I came up with a slightly different approach for this section. I had a look at all the themes on themeforest, picked one I liked and used that as my style guide for the front-end. It’s a good starting point and will help front-end developers and marketers develop collateral in the future. At some point I’ll create a style guide that will serve as the authoritative document for all front-ed design, marketing and branding but this will suffice. For now, I don’t need to waste time, money, energy and effort when I’m not sure what the market reaction will be to the product. User feedback will provide data on how to proceed here.

Live URL and Dev URL: With so many changes going on and communication through different channels it was getting really confusing to keep track of a) which urls were the old urls b) which urls were the new dev urls and c) which were the dev urls that have been moved into production. Further to this, we implemented a url naming standard so there’s a place for everything and everything is in the right place. An organised Product Owner is a happy Product Owner. Image: As mentioned above, this wireframe is the authoritative document for the whole project. It allows me to take a helicopter view of the whole project to get a sense of where we’ve been, where we are and what is the highest value I can deliver next. With that in mind, I’m able to chunk the work down into Themes, Epics and User Stories then communicate this to the developer. I add the link in every template but the actual screenshot changes depending on what’s being working on. I also include it as a visual representation for the developer so there’s zero misinterpretation of where we both should be and what should be worked on. It’s just another fail safe to keep the team ticking along smoothly.

User Experience and User Story

User Experience design / Mockup: In the image above you can see a thin sliver of gray. This is a screen capture of the feature being built. This screenshot is taken from a much larger page that represents the whole page. I could have added a link to the whole page but that would have meant the developer would have had to click the link and navigate the whole page to find the feature this User Story was for. Instead, I chose to add the screen capture to keep the information within the User Story narrow. There’s enough high level information to guide the team and remind them where they are within the whole project. This section is design to narrow the focus, like a “laser,” on to just the feature being created.

There are a bunch of user design tools out there that you can waste a lot of time reviewing, add overhead to your project with a monthly subscription and introduce a learning curve that will slow you down in your project. For my project I chose PowerMockup because it’s an add-on for PowerPoint which I already know how to use, is only US$59.99, provides a comprehensive array of wireframe templates. But, most importantly, it allows me to do the job I need to do which is communicate what’s in my head to the developer quickly, easily and in a way he understands.

I’ve added the User Story and Acceptance criteria below as it’s not clearly visible in the image.

User Story

As a logged on user

I want to be able to enter a number between 1 and 30

So each popup is displayed for the number of seconds saved in this field

Acceptance Criteria

Given I’m a logged on user on the Page Visits page

When I enter a number between 1 and 30 on the right hand side of the page

Then, when I click in the field, the word “seconds” should disappear

And if I type in a number outside the range of 1 and 30, the number in the field should be deleted and an error message should appear on the left of the field saying ”

add a number between 1 and 30″

And the popup, regardless of where it appears, should delay appearing on the front-end of the website for the configured number of seconds

And finish filling in/completing the rest of the Page Visits configuration

Then, when I click the “Create +” button at the bottom of the page, I’d like the value I entered to be saved in the configuration of the popup I’m creating

And if the user does not enter in a number between 1 and 30, or enters in anything other than a number between 1 and 30 i.e. letters, symbols etc, a notification should appear stating “please enter a number between 1 and 30”

Additional Information

  • The Confluence document I’ve used as an example only addresses the front-end functionality. It does not address the back-end requirements. Once the front-end is working as expected, the next Epic will be to complete the back-end functionality
  • I’ve automated the assigning of Issues so that when they are moved from the Product Backlog, to Sprint Planning, To Current Sprint, to QA, they are assigned to the appropriate person.
  • Every little chat style communication is done in Jira or Confluence. It’s much quicker and easier to use the chat feature in Upwork. Once the conversation has been completed, I make the necessary changes in Jira and Confluence

Feedback from Interviewer

The interviewer was kind enough to provide some constructive feedback on how I could improve my acceptance criteria which I’m really grateful for and has immediately helped me write better User Stories and acceptance criteria. Below are the suggestions for improvement:

  • In your attached file you discuss setting a number, validation messages (eg saving a blank), and how the number affects other parts of your system in the one set of Acceptance criteria. This is a conflation of multiple ideas that could actually be distinct and deliverable independently, if so, you may find developers find it easier if you separate your concerns.
  • Try to break up your Acceptance Criteria into scenarios along boundaries like Create, Retrieve, Update, Delete, Sort, Filter. In your case you could have a scenario for update on a happy path 1-30 then another for update as blank to throw the validation, then another for how the setting affects the pop up behaviour. In this way the first two scenarios can be done without the popups being implemented.
  • Try to separate concerns, for example you talk about setting the number while also talking about how it affects behaviour of pop ups. You might  put an “and” condition on other stories that reference this setting when it should affect the pop up behavior.

Over to you. If you found this blog helpful or have any questions, please feel free to reach out or comment below.

Write a Comment

Your email address will not be published.