Using Jira to manage work for docs.folio.org

Review the upcoming release to help figure out what might need to be added to or changed in documentation

There are various ways to review changes, you should consider doing them all, depending on how your particular area of FOLIO typically shares information.

• Ask product owners to share with you what features are planned for the upcoming release. Product owners are listed by module at FOLIO Module/JIRA project-Team-PO-Dev Lead responsibility matrix. Ask them to share links to any existing JIRA boards that might be helpful for tracking feature development by release.  For example, the Acquisitions product owners maintain this Kanban board that's helpful.
• Review the release notes. Product owners update release notes at various times, so just because something is not on the release notes doesn't mean it isn't happening in the release, but you can be assured that if something is listed in the release notes, it can be expected to appear in the release, barring discovery of unexpected bugs.
• Review jiras assigned to the specific release. In Jira, you can search for issues that are assigned to a specific release. From the issue search, add the "Release" criteria from the more menu, and then choose the release you are working on from the check box. For some areas of FOLIO, it's helpful to also choose from the Project menu to narrow the list down further. EG, you can choose the UXPROD project to just search for new features in a release and not also see bugs or tech debt or other work happening that doesn't necessarily need documentation.
  
  

Create a DOCS Jira for each discrete piece of documentation you need to do

Once you have an idea of what changes need to be made, you can then create jiras for them. Various folks have organized their docs jiras in different ways, but in general it is helpful to create a DOCS Jira for each new feature you need to review for documentation, or for new bugs or workflow changes. It's much less helpful to just have, say, one Jira for "Poppy RA Work".

To create a DOCS jira:

1. Make sure you are logged into the FOLIO Jira (https://folio-org.atlassian.net)
2. From the top menu, click "Create"
   
3. The Create Issue box appears in the middle of the screen. From the Project List, choose FOLIO Documentation (DOCS)
   
4. From Issue type, choose Task
   
5. In Summary, provide the subject line for your ticket. It's helpful to start the subject line with the planned release (or "TBD" if you don't know for sure) since the "Release" field is not enabled for the DOCS project. Then in the Description, provide a brief description of what needs to be documented, or what the Jira is meant to help you track. It's helpful to link to the Jiras either in the description, or using the Jira Linked Issues functionality. (The only reason to not do the latter would be if you had not talked to the feature PO about it, since sometimes it can be confusing to link the Jira if the feature itself is already closed as done.)
   
   
   
   
6.  (Optional) Scroll down to the Issues field to link this DOCS JIRA to the related feature Jira(s) that triggered this documentation need.  

7. Scroll down to the Assignee field and choose the assignee name (if you are assigning the ticket to yourself, just choose "Assign to me" on the right.)

8. Finally, click the Create button on the bottom right to create the ticket.

Working with open Jiras for documentation

There are several different ways to find the documentation jiras that you need to work on. You may decide that you want to set up a dashboard to see them; creating a Jira dashboard is not difficult, but it's beyond the scope of this documentation.

If all you want to do is see what Jiras are assigned to you, the simplest path is:

1. Go to https://folio-org.atlassian.net and log in
2. Click on the Issues menu at the top of the screen
3. From the Issues menu, choose Filters > My open issues. If you are already on the issues page, you can also choose My open issues from the left side menu.
   

Typical practice with an open Jira is to do the following:

1. Review the documentation need and determine if documentation changes need to be made.
   1. If they don't need to be made after all, choose Workflow > Closed with a resolution of "Won't do" and leave a brief comment so anyone looking at the Jira later can tell what happened.
2. If documentation changes need to happen:
   1. If you will be doing the documentation change and creating the GitHub pull request (PR) immediately after, go ahead and do so. Once the PR is created and waiting for approval, change the ticket to Workflow > Closed "Done" and leave a comment like "PR created for Nolana release, closing Jira ticket"
   2. If you will be working on the documentation change over the course of a few days, click the In Progress button at the top of the Jira to change the status, and leave a comment  like "Working on update to requests page and settings documentation". Then, when the documentation is finished and the PR is created, change the ticket to Done and leave a comment like "PR created for Nolana release"