Agile - how do you document the app you built?

Question

My question is after you write the initial user stories and then do months of "agile" back & forth with the business analysts/project managers how do you reverse engineer the actual requirements?

Our QA lead is constantly frustrated asking us "how is this supposed to work". I'm against keeping a giant word document with requirements b/c we would have to manually go and update it after EVERY ticket, yet that WOULD solve the problem.

Can anyone offer a more reasonable solution that would somehow leverage JIRA issues into a "living" document that would be a great reference for QA and even the devs with bad memories as they maintain the system? It can't just be r4j because all I see there are containers for tickets - I don't want to read multiple tickets - I want ALL the requirements captured accurately. Suggestions that work well for you?

Answer 1

There's no easy answer to this. I face this problem with many customers of mine.

First, you need to start building the documentation referring to the last release. Then, for every sprint, you need to prepare a new version of the documentation with the increments in the sprint. When the sprint is completed successfully and the code is merged, you have to merge the new documentation with the current one.

You can use Confluence for documentation, and on each update, you can reference the related Jira issues that caused the update.

Answer 2

A really good solution to this problem is to use Behaviour Driven Development (BDD).

With BDD you define the behaviour of your system and create tests to verify that behaviour. The BDD scenarios then become living documentation, not only representing the behaviour of your system, but also validating that it is behaving as expected.

If requirements change during development then the BDD scenarios and tests will naturally change as well. The system behaviour is literally defined by the documentation, so you can have confidence it is up to date.

Answer 3

One way which worked well for us was as follows:

• Designer gets screens approved by Product Owners or Stakeholders
• Approved screens are saved in Confluence with expected user actions and results
• The above screens with user actions and results serve as test cases for Testers
• If the screens are changed then the Confluence pages are changed to reflect the same
• Related issues to the screens may be tracked on the bottom of the page

This is a good article from Atlassian explaining the different kinds of documentation: https://www.atlassian.com/software/confluence/documentation#types-of-documentation