Jira Workflow Best Practices - Part I
Tags: atlassian, jira
Published: 2022-01-10 11:15:21

Author: Ismael Jimoh

This series of three blog posts shares some of the Jira workflow best practices I have garnered in my years of working as an Atlassian consultant.

As Jira Administrators we often have to setup, modify, or clarify workflows with our teams. Who am I kidding? This is most likely 50% of the work we do - and the list of beautiful things goes on and on and on.

Each time we think, should I just get this over with quickly so that I can get back to more interesting things; such as creating the next fantastic automation, troubleshooting some interesting problems that leave you with headaches and sleepless nights, or maybe even planning the next upgrade after reading through five pages of change logs to see what's new in Jira and what fancy new features someone definitely wants. This all runs through our heads rather than performing something we may at times consider mundane or repetitive such as managing a workflow.

However, to have a smoothly running team/organization, we need to ensure that our processes are properly translated into any tools we work with - in this case, Jira. Hence, we all have to work together to build sustainable workflow practices that:

-   are easily understood;
-   clearly define the team's business process;
-   allow teams to work in a way they understand.

This topic will be divided into a 3-part series in which the first part focuses on ideas that are not tied to the workflow itself, but something more general, such as the benefits of documenting and involving the right people; the second focuses on the best practices with the workflow design itself; and the third on the topic of governance and how we can best handle delegating workflow modification to others.

Without further ado, here are some of my recommended best practices:

Document Everything
-------------------

Discuss the importance of documenting everything. Really everything. Proper documentation serves many purposes.

-   It saves time for other administrators in case the designer is on leave;
-   it helps with the transfer of knowledge in the form of a sample of *"how to work"* in general;
-   and it helps with onboarding.

Documentation ensures that what has been implemented was approved by all users.

The tool of use could vary from *Atlassian Confluence* to any documentation tool that is used in your organization (we would recommend any with the **versioning** feature as this ensures that you do not need to create multiple documents such as My Awesome Workflow v1, My Awesome Workflow v2, e.t.c.). Another factor to look out for in the documentation tool is the capability of either direct integration to a diagramming tool such as [Miro board](https://miro.com/aq/ps/apps/?utm_source%3Dgoogle%26utm_medium%3Dcpc%26utm_campaign%3DS%7CGOO%7CBRN%7CDE%7CEN-EN%7CBrand%7CExact%26utm_adgroup=%26utm_custom%3D10031645019%26utm_content%3D437611915831%26utm_term%3Dmiro%20app%26matchtype=e%26device=c%26location=9061132&gclid=Cj0KCQjw-4SLBhCVARIsACrhWLVgWGGLL4aumJcAM_wbdI1z-XpyBFC0MyVuxb7hBH8VZ0KN-3IIZnMaAvDrEALw_wcB "Miro board"), [Draw.io](https://www.lucidchart.com/pages/landing/draw.io?utm_source=google&utm_medium=cpc&utm_campaign=_chart_en_tier1_desktop_search_nb_exact_&km_CPC_CampaignId=2083827036&km_CPC_AdGroupID=78426528124&km_CPC_Keyword=draw%20io&km_CPC_MatchType=e&km_CPC_ExtensionID=&km_CPC_Network=g&km_CPC_AdPosition=&km_CPC_Creative=417002582351&km_CPC_TargetID=kwd-308202328027&km_CPC_Country=9061132&km_CPC_Device=c&km_CPC_placement=&km_CPC_target=&mkwid=s6vjJOc5V_pcrid_417002582351_pkw_draw%20io_pmt_e_pdv_c_slid__pgrid_78426528124_ptaid_kwd-308202328027_&gclid=Cj0KCQjw-4SLBhCVARIsACrhWLXxMNZsEgoh81TjyFLD5GaPzpxS2e02YXlMcGrTOP2Y6Y3KgmPZ_0saAiG_EALw_wcB "Draw.io"); this ensures an up to date version of diagrams or make sure that the documentation tool allows you to import an image of the agreed workflow diagram as a file, which you can then attach to the documentation page.

Involve All Key Stakeholders
----------------------------

A room full of people is a disaster waiting to happen for as you know, "Too many cooks spoil the broth!" However, a room without the **right** people could easily be just as big a disaster.

Hence, my suggestion here is having the most important stakeholders in a business process present when you are defining your workflow. Have each person understand the process and document every meeting and set process flow. Get a sign-off and buy in from them and, should the need for change come up, at least try and notify these people of the change before you apply it to the production instance. Potentially, implement it in your test instance first prior to deploying it to production.

Support
-------

Lastly but definitely not the least, no one knows everything under the sky. We may need a little help here and there, and here is where a support channel or community comes into play. Knowing which support channels are available, how to access them and what questions are appropriate for each support channel is important. Hence, here we would share some information to assist with this. Below are a few channels that could greatly help you :

1.  The following official Atlassian **support** channels are available should you hit a roadblock. They (Roadblock) can be simple or really complex as it depends mainly on what the issue is and what knowledge you have internally. Atlassian provides two key support channels for assistance:

-   [Atlassian support](https://support.atlassian.com/contact/#/ "Atlassian support"): is the official Atlassian support channel to reach out to for most questions you may have. It covers support that includes Payment issues, questions about features, technical questions, to name a few. Here, you would be working directly with Atlassian so you would not need to worry about data leakage due to governmental laws or company policy. You usually have safe communication where Atlassian is responsible if the information is leaked from their environment, and a support agent would be happy to jump in to help. Note however that very basic questions that are not necessarily problems might result in your being sent to their official documentation or the second channel below. Also, tickets and questions are answered based on the priority level or the support level tier system (You can read more about this [here](https://confluence.atlassian.com/support/atlassian-support-offerings-193299636.html "Confluence")).
-   [Atlassian Community](https://community.atlassian.com/ "Atlassian Community"): As the name implies, this is a **community**. A very active one if I may say so myself with people spending their OWN time assisting you with your questions, so please be nice (Zwinkern). Technical questions, basic questions are very welcome here, however, I would advise having some knowledge of the tool as the suggestions you receive require that you perform something later and if you cannot, then this defeats the purpose of the community as they cannot access your instance to do your job for you. (I understand this might sound harsh, but a certain amount of knowledge is indeed needed for these two types of support). Also, I would recommend **against** posting anything into the community that would be considered sensitive (say usernames, passwords, email addresses, scripts which perform authentication and contain credentials or business secrets taken as images and attached to the community, etc.).

2.  In addition to the above, and when you want a more hands-off approach to managing things (includes if there is a lack of technical depth within the organization), we recommend reaching out to an Atlassian Solution partner such as ourselves here at kreuzwerker GmbH. Solution partners can assist with either training your internal employees to help with adoption, knowledge upscaling for the employees, or even helping with the development of the business process itself. Often times, these agreements with Solution partners come with support post implementation, or this could be purchased as an on-demand basis. We recommend that you factor this into your contact agreement with the Solution partner. You can find a list of Atlassian solution partners [here](https://www.atlassian.com/partners "Atlassian Partners") and we would always recommend considering a Solution partner near where you are located to ensure that language, timing and even meeting locations do not hinder your collaboration. (Note that you can also ask Atlassian to recommend a partner for you).

Unfortunately, this brings us to the end of the first part of the series. Do check back for the second part. I hope you find these useful.