A JAWS Screen Reader User’s Guide to Jira
When I first started working on the Sakai Project, some 18+ months ago, I knew very little about the Sakai LMS. Prior to that, I had never worked on an open-source software project, let alone an international, multi-partner collaboration of that scale, so I hadn’t yet been exposed to all of the insider tools, processes, and systems that are needed to effectively manage an agile software development process while supporting a geographically dispersed team. So, I really had no idea of what to expect, or exactly what I was getting myself into.
This much I knew for certain. Learning Experiences had retained my services to help Sakai with Accessibility and Quality Assurance. The plan was for me to embed myself as a member of the Learning Experiences/Sakai QA team. Starting with working my way through their existing QA Onboarding process, I was to evaluate every aspect of the organization from an accessibility perspective, based on my own immersive experience.
In addition to my rather vague marching orders, I was given access to a calendar with information about the various Sakai Community meetings. It wasn’t much to go on, but it was a good place to start. Being that it was the beginning of the week when I began working on Sakai, it just so happened that the first of these meetings was the regularly scheduled Monday afternoon “Jira Triage” call, whatever the heck that was?
When I logged onto the BigBlueButton web conferencing system for the first time and followed the directions to connect through to the room where the meeting was being hosted, I was greeted by the voice of a somewhat surprised Shawn, one of the people responsible for overseeing our Jira triage process. Now Shawn and I have since become good friends, but at the time, he had no idea who I was, or why this random dude was joining their “Jira Triage” call.
Unfortunately, when it got around to him asking, I didn’t really have a good explanation for why I was there either, other than I was just making the rounds to try and get the lay of the land. But in almost stereotypical nice guy Shawn fashion, he was helpful and welcoming and went to great lengths to explain all about Jira, and the purpose of the “Jira Triage” calls.
And thus began my education, and my long and humbling journey to tame the monster known as Jira.
JAWSilla vs. Godzilla
Of course, Jira is not a monster, well, maybe not in the literal sense. It’s a place to report and manage issues, such as in software.
According to the Jira page on Wikipedia,
“Jira is a proprietary issue tracking product developed by Atlassian that allows bug tracking and agile project management. The product name is a truncation of Gojira, the Japanese word for Godzilla. The name originated from a nickname Atlassian developers used to refer to Bugzilla, which was previously used internally for bug-tracking.”
I’ll be honest, prior to the Sakai Project migrating to the Jira Cloud version last year, as a JAWS screen reader user, I got along with our old version of Jira about as well as Mothra got along with Godzilla, which on a scale from 1 to 10, falls somewhere in between a giant, oversized fly swatter and a super-charged Sears & Robbuck electric bug zapper.
Now in fairness to Jira, I hadn’t needed to do much more than casually follow along on a list of issues in the filter during our “Jira Triage” calls. However, when we started to ramp up our new “WAM-A11Y” review process, which we’ll talk more about in the next part, it became apparent that I would need to be more hands-on, and that’s when the real breakthrough started to happen.
During our Thursday interactive test sessions over Zoom, I would use screenshare with the computer audio enabled, so Shawn and Gonzalo (the other two members of our elite “WAM-A11Y” review team) could virtually look over my shoulder, and methodically direct me through a series of carefully choreographed keystrokes, or sometimes a trial and error of tabbing and arrowing and pressing enter, until we were able to unlock the right combination needed to perform a particular task.
It was a long, tedious process that tested our patience, and for me personally, my ability to stifle my profanity, but each time we figured out something new in Jira, we thoroughly documented our steps, and would then take what we learned and apply it to the next problem to solve.
Even then, there are things that we still haven’t been able to figure out how to do in Jira using the JAWS screen reader, for example, how to use the “Mention” feature to select a user from the drop-down list that you would like to add to the ticket. But we recognize that this is a work in progress, and we continue to work on unlocking more of Jira’s functionality, and with each new discovery, we help to improve the user experience for those of us who rely on keyboard/screen reader navigation to get around in Jira.
Now, before we get into describing some of these specific Jira use cases, I thought I would start by sharing a link to where you can sign up to access a free trial for Jira Cloud, hosted by Atlassian, if you are interested in trying out Jira for yourself:
https://www.atlassian.com/software/jira/free
Moreover, for those of you who would like to try and recreate these steps to simulate the Jira experience for a JAWS screen reader user, you can visit the Freedom Scientific web site to download a trial version of JAWS that you can run in 40-minute demo mode.
The following examples are detailed step-by-step descriptions for how a JAWS screen reader user can perform some of the more common tasks in Jira. It should be noted that I was using JAWS 2022 and the Google Chrome web browser when preparing these notes, so different versions of JAWS, or other screen reader/web browser combinations may yield completely different results.
Also, for optimal use with the JAWS screen reader, I found that it was best to switch Jira to the “List” view.
Part 1 – Navigating Jira – Some Basics
You can think of Jira as this robust, collaborative workspace that teams can use to report, track, and resolve issues. This is a gross over-simplification, but basically individuals create tickets to report an issue, and then an individual or group is assigned to work on the ticket. Issues can be tracked by their unique ticket number, or filters can be used to sort for certain types of tickets.
For this article, we will be focusing on how to review and edit existing tickets, and will look to cover how to create new Jira tickets in a future blog post.
So, this first series of tips presumes that an established, well-seasoned software product or project has already set-up multiple types of filters to manage different aspects of the software development life cycle. Filters basically allow teams to easily parse Jira by using any number of variables like labels, components, assignee, effects version, status, etc. to sort for those issues that are pertinent to a specific role, or the related functions that an individual or group is responsible for fulfilling as part of their work on the project, or simply to find the tickets they’re looking for.
This was the case when I started to help with accessibility testing and quality assurance work for Sakai. As I got acclimated to my new role on the Sakai QA team, I learned that there were certain Jira filters that the other QA folks and I would need to use to keep track of issues flagged for testing or verification, or because of my expanded role, those accessibility-related tickets that might require additional screen reader testing. But these issues would only show up in our cue if the ticket had met a specific set of criteria, like it contained a particular label and/or its status had been changed to resolved. Otherwise, the ticket might still show up in separate filters used by the Dev team, or the Sakai Release Manager, or any number of different working groups, again, based on their own criteria that they established related to their specific role/function. There are also more generic filters that cut across multiple different roles/functions, an example being the filter used by the cross-functional team tasked with reviewing/opening new tickets as part of the Jira triage process that was referenced earlier.
But Sakai is a living, breathing thing, and as circumstances dictate, our processes change and evolve, additional filters have been created, like the series of filters that we are now using to track issues through our two-part “WAM-A11Y” review process.
Reader’s note: The acronym “WAM” refers to the organizations of the three individuals in our small workgroup, although we often joke that it stands for “Whack-A-Mole”—a fitting moniker for a group committed to tracking and resolving accessibility issues…
How to navigate through the parts of a Jira ticket
1—Again, while still in “List” view--when first opening a filter list and navigating to the first item in the filter’s table, press enter on the issue number or summary to view details of the Jira ticket
2—After the page refreshes (note: it might take a few seconds for the page to fully load) use the CONTROL+HOME keyboard command to jump to the top of the page
3—Press the JAWS hot key “H” to jump to the level 1 (H1) heading
4—You can continue to press the JAWS hot key “H” to cycle through the rest of the headings until you land back on the level 1 heading.
5—You can also use the INSERT+F6 keyboard command to bring up a list of headings to view/jump to specific parts of the Jira ticket
(Note: In the below examples, we will describe how to use tab, shift+tab, and the arrow keys to access other parts of the Jira ticket for performing specific tasks, as well as some keyboard commands/shortcuts that screen reader users will want to take special note of)
How to move to the previous Jira ticket in a filter list
1—Use the JAWS pass-through command insert+3 and then press “K”
2—When the page refreshes, use the control+home keyboard command to move focus to the top of the page
3—Press the up or down arrow key to get JAWS to read the ticket number
4—Press the JAWS hot key “H” to move to the level 1 heading where a summary of the Jira ticket is displayed
How to move to the next Jira ticket in a filter list
1—Use the JAWS pass-through command insert+3 and then press “J”
2—When the page refreshes, use the control+home keyboard command to move focus to the top of the page
3—Press the up or down arrow key to get JAWS to read the ticket number
4—Press the JAWS hot key “H” to move to the level 1 heading where a summary of the Jira ticket is displayed
How to use the “search” option in Jira
1—Use the JAWS pass-through command insert+3 and then press “/” to insert your cursor directly into the edit field for the “search” option
2—Type in the information for a specific Jira and press enter (for example, the Sakai Project uses the prefix “SAK” for all of its tickets, so a typical Sakai Jira may take the form “SAK-12345” while other projects may use their own unique prefixes and naming conventions)
Or 3—type in any key terms that you would like to search for and then use the down arrow key to navigate through the list of search results to look for any relevant matches.
How to switch between the “General” and “Testing” tabs in Jira
(Note: I believe the “Testing” tab is a custom tab for Sakai. I’m not sure other Jira systems will have a “Testing” tab, however, other systems will have other tabs, so it’s still relevant to be able to navigate between different tabs. Just mentioning it here, as this tab may not be called “Testing” in your instance of Jira. Although not specifically referenced here, there is also a “Release Notes” tab next to “General” and “Testing” in this area that might be available by default in other Jira systems.)
1—From the level 1 heading, press the JAWS hot key “H” once until you hear JAWS say, “Description”, or “Test Plan, Heading Level 2”
(Hint: When you first open a Jira ticket, you may want to first use the control+home keyboard command to move your cursor/focus to the top of the page)
A—If it says “Description”…
2—Press shift+tab twice to navigate back to the “General” tab
3—Once on the “General” tab, you will need to hit the right arrow key once to navigate to the “Testing” tab
B—If it says “Test Plan”…
2—Press shift+tab twice to navigate back to the “Testing” tab
3—Once on the “Testing” tab, you will need to hit the left arrow key once to navigate to the “General” tab
Part 2 – Reviewing & Editing Jira Tickets
Before I launch into a description of how to perform some of the more common Jira tasks, I thought it would be helpful to start by expounding on my role within the Sakai community and the specific ways I have found that I need to be able to access/use Jira.
Like I said before, I am a member of the Sakai QA team, so one of my primary functions is that of quality assurance. Yes, I am focused on accessibility/usability, but its quality assurance all the same.
So, when there is a ticket created for an accessibility-related issue, it’s my responsibility (along with the other members of our “WAM-A11Y” review team) to determine whether it’s indeed a valid accessibility issue, while making sure the Dev team will have actionable information (i.e. a thorough test plan, accurate description of the test environment, recommendations for fixes that adhere to A11Y best practices/standards, etc.) to begin working on the ticket.
Of course, user testing (specifically keyboard/screen reader testing) is the other important function that I perform. Occasionally I will be asked to test something out with my screen reader prior to a ticket being created, but mostly I am reviewing, commenting on, and/or adding more detail to tickets that are already in the cue, or I’m going back and testing to verify that things are working properly with my screen reader after a fix has already been made.
For the above reasons, I need to be able to review the details of a Jira ticket, including its summary, description, test plan, and comments.
I also need to be able to edit test plans, create comments, and attach files such as demo videos.
Finally, I need to be able to add certain labels to tickets when completing our 2nd-level “WAM-A11Y” review, and/or flag it as an issue that will require screen reader testing to verify.
How to navigate to and read an existing “Description” in Jira
1—From the “General” Tab…
2—Press tab to insert the cursor onto the “edit description button”
3—Press shift+H to move the cursor to the “Description” level 2 heading.
4—Alternatively, from the “edit description button” you can up arrow backwards through the content
How to navigate to and read an existing “test plan” in Jira
1—From the “Testing” Tab…
2—Press tab to insert the cursor onto the “edit test plan button”
3—Press shift+H to move the cursor to the “Test Plan” level 2 heading.
4—Alternatively, from the “edit test plan button” you can up arrow backwards through the content
How to create/edit a “test plan” in Jira
1—From the level 1 heading, press the JAWS hot key “H” once until you hear JAWS say, “Description”, or “Test Plan, Heading Level 2”
A—If it says, “Test Plan, Heading Level 2”…
2—Then you can simply tab once to access the edit button
3—Press the enter key to enable editing.
4—When finished, tab to the “save” option and press enter.
(Hint: It might be easier to first create your test plan in a MS Word document so you can just cut and paste the information into the edit field)
B—If it says “Description”…
2—Press shift+tab twice to navigate back to the “General” tab
3—Once on the “General” tab, you will need to hit the right arrow key once to navigate to the “Testing” tab
4—Once on the “Testing” tab, press tab to access the edit button
5—Press the enter key to enable editing.
6—When finished, tab to the “save” option and press enter.
How to review “comments” in a Jira ticket
1—From the level 1 heading, hit the “H” key until you hear JAWS say, “Activity”
2—Press the down arrow key until you come to the first comment in the list
3—If the sort order is from “newest to oldest” (which is the default setting) you will want to switch it so the oldest comments are listed first, which will move the option to edit a comment down below any existing comments that are displayed, so the editable comment field doesn’t trap your cursor and prevent you from being able to scroll through and read all of the comments.
(Note: Once you change the comment sort order, Jira will remember the last sort order for your session or your account, so it should be in the same sort order as the last time you read comments.)
How to add new comments to a Jira ticket
1—From the level 1 heading, hit the “H” key until you hear JAWS say, “Activity”
2—Press the down arrow key until you come to the first comment in the list
3—If the sort order is from “newest to oldest” (which is the default setting) you will want to switch it so the oldest comments are listed first, which will move the option to edit a comment down below any existing comments that are displayed, so the editable comment field doesn’t trap your cursor and prevent you from being able to scroll through and read all of the comments.
4—Use the down arrow key to navigate into the edit field to add a new comment.
5—Alternatively, you can use the JAWS pass-through command insert+3 and then press the “M” key to insert your cursor directly into the edit field for adding a new comment
6—When finished adding your comment, tab to the “save” option and press enter
How to add labels to a Jira ticket
1—From the level 1 heading, continue to press the JAWS hot key “H” to cycle through the list of headings until you come to the “labels” heading
2—Use tab or down arrow until you hear the screen reader say, “edit labels button” and press enter to insert the cursor into the label field
3—Type out the label (for example, “wam-a11y” -- all lower case)
4—If the issue requires additional labels, for example, further QA testing by a screen reader user is needed, also add a “screen-reader-qa-needed” label
5—Tab to the “confirm” button and press enter
6—Navigate to the H1 heading and then use shift+tab or up arrow to navigate to the “return to list” option and press enter
(Note: “WAM-A11Y” and “screen-reader-qa-needed” are Sakai-specific labels which are being used here for demonstration purposes. Other Jira projects will have their own unique labels.)
How to use the Jira keyboard shortcut to add a label
1—Use the JAWS pass-through command inser+3
2—Press “L” to place your cursor directly into the editable area for typing in a label
3—Start typing the label you want, and as it auto completes, simply press enter to add the label
4—Pressing the left arrow key will navigate over to where you can see which labels are already on the ticket (will indicate “1 of 4,” “2 of 4,” etc.)
5—When finished, tab over to the “confirm” button and press enter to add the labels
How to change the status of a Jira ticket
1—From the level 1 heading—press the JAWS hot key “H” to cycle through the headings until you land on the “Activity” heading.
2—Down arrow through the “comments” history and add new comment edit field until you reach the “open- Change Status button” (which should be in its “collapsed” state)
3—Press enter on the “open – Change Status button” to expand its menu options
4—Down arrow to the desired selection (i.e. “Awaiting Information”)
5—Press enter to apply the status to the ticket
This concludes our introductory help document about using Jira with the JAWS screen reader.
For any JAWS screen reader users out there, please let us know if you found this information to be helpful. Additionally, are there other common tasks in Jira that you would like to be able to perform with your JAWS screen reader? We’d like to know about those as well…
For those ambitious developers out there, we encourage you to take up our challenge, and demo Jira with the JAWS screen reader for yourself. Do you have suggestions for how to improve the accessibility of Jira? Can you suggest other keyboard-specific work arounds that can add to our current body of knowledge and improve the experience for screen reader users?
Stay tuned for our next installment where we will describe how to create a Jira ticket.