2

I have been in meetings with product managers discussing how to document our app when something dawned on me.

If we spend all of this time creating the Jira infrastructure to manage Epics/User-Stories of our mobile app, then is it possible to just create product documentation from the tickets themselves?

All of the acceptance criteria, visual resources, & links to other stories are already there. If and when a technical writer would be tasked to create documentation, after 1.0 release, they would presumably just read from the tickets anyway. Can this copy/paste be avoided in the first place?

Has anyone heard of this, either with Jira or another product management tool? Is it something that just isn't done for good reason?

I am not a Product person and only have experience with Jira as a Software developer.

Improve this question

2 Answers 2

Reset to default
2

It depends on what you mean by "product documentation".

Jira does have the capability to produce release notes, if you are using the Releases and Fix Version capabilities. This capability exists for classic projects, but I don't believe that it exists for next-gen projects at this point. The release notes are a set of issues that have the version applied to them.

In theory, you could build queries that return various user stories. The workflow or labels would need to differentiate the work that has been released and is still active in production versus work that has been deprecated. This isn't true for most of the workflows that I've seen, which end with the work being in a final "done" or "released" or "deployed" state.

There are also test case management tool plugins that can incorporate test cases, including BDD-style tests, into Jira. This may also be useful, but you may run into the same problems as using user story issues - you need a way to identify test cases that correspond to releases and exclude deprecated test cases.

If you're using Jira, I would recommend building documentation in a tool such as Confluence. It has integrations with Jira that can be used to incorporate Jira issues into pages. It also has integrations with various diagramming tools. The structure can be modified to form hierarchies of pages that can be exported into documents. It's much closer to what would be expected for knowledge management and documentation, especially if extended with plugins.

Improve this answer
3
  • Your last paragraph is more so what I'm talking about, knowledge management. I suppose there are tons of plugins that can automate building confluence page content with jira tasks, the tasks being the source of truth.
    – flopshot
    Commented Apr 2, 2020 at 23:22
  • I know that code should be self documenting as much as possible, but BDD on iOS projects can be limiting due to the constraints of the Xcode build tools. My intuition is just telling me that well thought out tickets can be the source of truth for knowledge management, as you put it. Why spend time creating Confluence docs from scratch when we have mountains of tickets with the exact same information.
    – flopshot
    Commented Apr 2, 2020 at 23:24
  • 2
    @flopshot Managing the life cycle of tickets beyond completion or deployment is likely difficult and time-consuming. One ticket can be removed or modified by another ticket, and once you get to thousands of tickets, it can be difficult to manage the relationships and ensure accuracy. Tickets generally aren't meant for knowledge management but can help support a knowledge management system.
    – Thomas Owens ♦
    Commented Apr 3, 2020 at 10:08
0

Yeah, this is a common problem. All this valuable knowledge is "locked" in Jira - and essentially disappears once the task is "done" - or at least very hard to find.

Look into tools like Userdoc.fyi, it helps move your requirements out of Jira and act as the source of truth - and then sync them Jira... You want your requirements in a "Requirements management system" - not a "Project management system".

Improve this answer

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.