We use cookies on this site to enhance your experience. Visit our Privacy Policy for more info.

Get Started: Atlassian Best Practices

Lorenzo Phillips | May 18, 2018

Atlassian products are highly customizable and therefore many organizations get into tough situations because they didn’t realize the impact of their decisions in both the short and long terms. This article will provide a few best practices for JIRA and Confluence to assist organizations that are new to the Atlassian platform in hopes of helping them avoid bad user experiences.


  • Determine your project structure prior to using the tool: Typically JIRA projects are setup based on products or teams. It is critical to determine a standard practice for projects to ensure they can be standardized in a way that it is easy for resources to move between them. You don’t want the projects functioning so different that there is a steep learning curve for the end-users.


  • Global field values: It is better to determine what the values of native fields will be up front to avoid negatively impacting projects later on. A good example is the Resolution field. It comes with a default set of values. The existing values can be modified or deleted and new ones can be added. More often than not, new users will use the default values and years later a new project may decide it doesn’t like the current values. Changing the values at this time can have severe impacts on the other projects as well as legacy tickets in the system. Review all of the global field values up front and avoid a disaster later.


  • Limit the number of available Statuses for workflows: JIRA workflows are highly customizable so if you’re not careful you can create a bunch of unnecessary statuses because users feel that somehow what they need is so unique that it has to be created. It has been stated that over 95% of the time, organizations have a lot of duplication in their JIRA environments when it comes to workflow statuses. The statuses should be driven by the defined process and not because someone requested it. Always fall back to the process if you get too much pressure to create statuses.


  • Create a standard set of workflows: The goal in JIRA is to standardize as much as possible and this will help with cross-project reporting and metric collection. Only create workflows that have a matching process linked to it. If users start requesting workflows that do not link to a process then you to direct them to the proper management level for proper discussions. If you allow the random creation of workflows, you will quickly find your environment to be messy and full of unused workflows that is much tougher to cleanup.


  • Use all available native reporting: Be sure the users are using the full native reporting capabilities before installing add-ons and plugins for this area. Users should be using Dashboards, Agile or Kanban boards, and the canned reporting contained within each JIRA project. A high percentage of the time, one of these options will provide the required reports. If the available options are not producing the correct reports, then you must review how the projects are entering their data to ensure it is being done correctly. Atlassian takes great steps to ensure JIRA is compliant with industry standards and that means the tools comes with industry standard reports. Only when you are certain that the data is being entered properly at the project level and that none of the native reporting options can meet the requirements should you review add-on and plugin solutions available in the Atlassian Marketplace.


  • Begin with open permissions on the spaces: While security is always an issue, Confluence is a collaboration tools. The worst experience a new user can have is not being able to freely collaborate with other resources. It is always best to start with the default permissions and only start locking the spaces and pages down when absolutely necessary.


  • Do not share accounts: Since Confluence is a collaboration tool many organizations will allow their clients to access it and participate in the collaboration process. The mistake is made when Atlassian administrators gets lazy and create a single customer account that is shared on their end by many resources. This presents a huge security risk and will lose the tracking of a specific user having dialog or providing great feedback. In short, Atlassian products should follow the same strict security guidelines implemented organizational wide. Do not allow the sharing of an account.


  • Use the native reporting capabilities: Confluence pages look like web pages on a website so the look and feel offers a familiar view to users. Confluence comes with plenty of macros, charts and tables to display information visually, so be sure to take full advantage of this to ensure your stakeholders and project resources are kept in the loop on progress and decisions. Also, be sure to utilize the dynamic content option when possible. Dynamic content updates on refreshes or regular intervals as defined. This means that users always have the most up to date information in front of them.


  • Integrate Confluence with JIRA: While the native reporting in Confluence may be adequate in most cases, there’s nothing like having Confluence integrated with JIRA to provide a view of critical tickets being worked on for releases. Rather than have the user jump between the tools or have two windows open each displaying a tool, the integration of the products shares key data on both sides. In Confluence, you can have a table that displays JIRA tickets that show content like who reported the issues, who the issue is assigned to, and the current status of the issue. In JIRA, a ticket can have a link to Confluence pages that contain requirements so developers can match their work with the actual requirement to ensure they implement the proper solution.

Global Level

  • User and Group Management: The importance of having a good user and group management strategy cannot be stressed enough. You do not want users that have left the company lingering around in the systems. Whether you use Atlassian’s internal management functionality, connect Atlassian to your existing Active Directory solution, or you are using or plan to use a single sign-on (SSO) solution, you must take great care to plan out the processes and procedures to ensure success. The rule of thumb is to treat Atlassian users and groups as you would treat users and groups in your enterprise. New users to your company will only get access to what they need to do their jobs. The same goes for Atlassian. If I am a Project Manger, I most likely don’t need access to the source code repositories. If I am a developer, I pretty sure I do not need access to budgets. Whatever strategy is implemented for the organization can be used as a starting point for authorizing users within the Atlassian platform.

Final Thoughts

The above information should be used as a guide to help you start off on the right track with the Atlassian ecosystem. You will have internal business rules that may hinder your ability to implement these best practices and that is totally fine. The goal is to have standards and implement those standards across the tools to make it as easy as possible to administer and maintain the tools. Standardization means you can have fewer resources dedicated to the Atlassian support team and when things go wrong you spend less time troubleshooting and more time contributing to your organization’s success.

To learn more best practices, download Insight's "Atlassian Playbook" by entering your information below.