This post describes how we use Jira and Confluence in a agile, distributed team to specify our products.
Jira – epic, story and sub-tasks
We are using the epic / story / sub-tasks model of JIRA to describe new products.
– EPIC = the big goal aka the elephant (> 1 month work time)
– STORY = describes a main feature of the EPIC aka the elephants leg (multiple days of work)
– SUB-TASK of a user story = describe the necessary (technical) steps to be implemented aka the elephants toe (< 1 work day)
An example
We are introducing a new product. This is our EPIC Jira issue. It could also be a new app or a new module of our product.
For each of the main features, we create a user STORY Jira issue that describes the detail feature (e.g. steps necessary to perform it, …) in high level language. There should not be any low-level details or technical specification. These stories are target for the product owner and customers, in a more abstract language. Our testers use them as baseline to create the functional tests. The developers use them to understand the context of their tasks.
The steps or required functions in our products are written in SUB-TASKs of these stories. This could be tasks for different team members as e.g. designer, developer, tester, platform, but also one sub-task for each platform (app, backend), or multiple sub-tasks for same developer teams. Such a sub-task should not take longer than a work day to implement. This sub-task describes the necessary tasks to be done, to get it working – focusing on unclear, unexpected, special or non-standard stuff. Global stuff is updated in the main story issue. All people relevant for the story are watching the story ticket to get informed about changes or clarifications.
Potential problems
Keeping in sync with all team members.
We’re using hip chat to discuss stuff, but not all team members are watching this. So it is important to update the user story and let relevant team member watch this issue, to get updated about changes.
Developing code and testing it.
Problematic since hunting the elephant takes longer and there will be more fixes + tasks to be done in the mean time. So we are using feature branches for the epic, user stories + sub tasks. Will be covered in a later topic.
Documentation
The Jira issues are used to create the initial (feature- and functional-based) documentation. Problematic is of course when the product ages and more features are added, updated and removed. Thus we strive to copy / update the content of the issues to our Confluence wiki, one for each product. Architectural documentation and non-functional requirements are documented directly in the wiki. Also part of a later post.
Only specify what is necessary
Mostly it is not necessary to describe everything in detail. Take care of special cases, things that are uncommon, unexpected or different. Reference to other issues whenever possible. Describe what should NOT be done and the borders of this issue.
Closing words
We’re always learning and striving to improve our workflow. What are your experiences? How do you specify the features of your products? Any pitfalls or typical problems?
Image credits: (C) by alexkich / Fotolia