Protecting Your Atlassian Tools Ecosystem Investment (Part 4): Best Practices for Configurations

In Part 1, Part 2, and Part 3 of this Governance series we discussed the people and processes supporting the human side of governance. In this part, we’ll take a closer look at the best practices around your system configurations.

Best Practices

Both Jira and Confluence can be used across the organization, and often provide mission-critical functionality to teams, programs, and executive leadership. As such, they should be managed in combination with other critical enterprise tools through a holistic approach to governance to ensure best practices are upheld and system performance is maintained.

As the size of your organization grows, the effort required to maintain and administer your Atlassian ecosystem will also grow. Your organization’s governance body should work on defining a set of best practices that combine general best practices for the Atlassian environment with those that apply to your business or industry. The best practices below are general in nature, but should be considered as a starting point to inform the creation of your organization’s specific best practices implementation.

Configuration management

Project creation

How and when to create a new project in Jira is not always a straightforward decision. Consider the following when determining your strategy for creating projects in your instance:

• • Think of Jira projects as containers for a body of work. The term ‘project’ can be misleading – it is not necessarily the same concept as a ‘project’ in your organization. Jira projects do not contain much metadata; there is no concept of project scope, start date, end date, or overall project status/progress (however certain add-ons can provide this sort of functionality).
  • Consider using Projects to group work in ways that are meaningful to your organization – you may consider creating a new Jira Project for each team, department or business unit. Projects are also useful for representing long-standing efforts that require a centralized source for reporting and status information.

• Jira projects consist of some elements that are specific to each project. Releases (fix version) and Component fields can be managed directly by the project administrator, and do not require system administration permissions to edit. In addition, roles and permissions can be managed at the project level. Consider projects that group related work for related audiences who may share similar permission needs.
• For organizations implementing SAFe or scaling methodologies, it may be useful to create a separate Jira Project for each level of organizational hierarchy – a Program level project can serve to contain the Program backlog of features and provide consistent permissions and reporting for Product Owners, Product Managers, and Release Train Engineers while separate Team level projects can allow teams to focus on their individual backlogs and metrics.
• Consider creating a limited number of standardized project “templates” using shared configuration schemes that will be used for creation of future projects. Evaluate new project requests against the existing template configurations, and then create all new projects with a shared configuration based on a template project.

Ultimately, the appropriate strategy for your organization is one that enables users to quickly understand where to find their work while also enabling quality data and reliable metrics and reporting. Separating work into multiple projects will not limit you from creating a backlog of work shared across multiple sources, but can help you identify the source of each item in the backlog via the project key. In general, try to find a balance between creating enough projects to organize your work in a meaningful way, and not creating more projects than are needed or can be easily maintained.

Issues, fields, screens and workflows

The key to managing all configuration objects within Jira lies in balancing the ability to customize these objects with the need for standardization, consistency, and ease of maintenance across the organization. In general, simpler is better. The fewer variations of workflows, screens, fields, and issues you can support which meet the needs of the majority of users, the better off you will be. Consolidating around a small number of variations on schemes will make it easier for users to understand how to use the system, and will reduce the overall complexity and cost of administration.

Some specific tips for deciding how and when to create or customize configuration objects in Jira:

• Consider creating a new custom issue type only if it represents a type of work that is drastically different than an existing issue type, there is a need to deviate drastically from an existing process or workflow, or if the input/fields needed are drastically different from another existing issue type. Too many issue types that represent similar kinds of work can lead to inaccuracies or omissions in reporting.
• Be judicious in creating new custom fields, as the number of custom fields can ultimately impact system performance. Whenever possible, try to genericize fields so that they may be used more widely by more teams, and use field context to help further tailor field values for specific projects.
• Keep workflow state names generic and consider how they may be used more widely across multiple workflows. Keep workflows as simple as possible while also providing teams the necessary information to track and manage progress. Consider using workflows to eliminate anti-patterns of silos and handoffs by encouraging more collaboration and communication through comments while keeping the workflow tailored to reporting on meaningful high-level progress metrics.
• Use tabs within screens to help organize information into smaller groups, and consider organizing fields according to where in the workflow they will be relevant. For example, the first tab of the screen should contain only the information necessary to create the issue and understand the basic context of the work, while additional tabs may contain information related to planning, or details about implementation that will be added later in the process.
• Before creating a new field, screen, issuetype, or workflow state search to see if there are any similar objects that can be effectively used or repurposed. Ensure that new configuration objects are sufficiently different from any already existing, and ensure they provide enough value to the business to justify the increased administrative overhead. While a single field, issue type, or workflow state may not represent a significant increase, over time a large enough number of custom configuration objects can make troubleshooting difficult and confuse users that may need to work in different projects or within different contexts in the system.
• It is also important to consider and even consult an expert if you plan to scale and integrate a tool like Jira Align.

Permissions, roles, & user access management

Jira provides a number of ways to manage permissions within the system. Permission schemes allow you to define which specific actions within the system can be taken by either an individual, group of users, or user role. It is critical to think thoroughly about your access management strategy as this is what will provide access and protect access to your information. It is an area that we often recommend you consult an expert if you are unsure.

For larger organizations, ensuring consistency in how permissions are applied can be critical. If your organization is using an external directory to authenticate users which has been integrated with Jira, consider keeping this directory as the single source of record for user information. In this case, you should rely upon the groups created by this external directory (such as Active Directory groups) to organize users and assign permissions to user groups. This ensures that permissions are applied consistently throughout the instance and that new users are onboarded with the appropriate permissions with no additional work necessary in Jira.

For smaller organizations or where Jira is the directory of record, consider using groups and project roles to assign permissions to users. This allows for a more standardized approach to the creation and use of permission schemes, but still allows project administrators to determine which users are added to the roles within their project.

Assigning permissions to individuals should only be done as a last resort, or for rare exceptions to the guidance above. Individual users added to permissions at the project level may be easily omitted from additional permissions or changes that occur after they were added, or may be inadvertently left in a role for which they should no longer have permissions.

Conclusion

In this installment of the Governance series we discussed Configuration Management best practices. Stay tuned for the fifth installment where we’ll cover migration configuration and other best practices for add-ons and health monitoring.

Briana Hall