Naming convention

Standardizing nomenclature is essential to maintain consistency across all Atlassian product configurations. In any case, despite being a very common practice in IT, many times as Atlassian administrators we fail to give this the necessary priority on the platform. This post is not intended to identify the benefits of doing so, but rather to share our own standard that we apply over and over again in each of the instances we manage for our clients.

Within the content we will find the following sections:

Our standard is always based on the following section structure

<Configuration Item>-<Project Category>-<Project Template>-<Template Number>-<Action/Target Status*>

The order will always be the same, what may vary is the number of sections that will depend on the level of configuration granularity that allows what we are configuring. For example, a workflow schema can only be configured at the project level, so the Template Number and Target Status sections would not be relevant.

Here I will break down each of the sections to simplify the understanding of how the name of what we are configuring is formed.

Configuration Item Section

The following table shows the options for this section.

Clearly, one can make one's own adjustment regarding this. The important thing is that in this section we provide information on what we are configuring, which has proven to be very useful for users who are starting to manage the tool.

Category Section

In this section of the name we seek to identify how global and massive the use of what we are using is. In general, Jira or Confluence categories are used to group projects that share certain common characteristics and, in many cases, their configuration.

In our case, when defining the name of the category, we use the description section to define the nomenclature of each of them and thus standardize the names to use in this section as can be seen in the image below.

Outside of the options we have in the categories, we will always have an additional option which is ALL which indicates that the configuration can impact projects of any category. In this way, our nomenclatures can have names that begin like WRKSCH-ALL or NTFSCH-ELT.

Project Template Section

As its name indicates, here we will be keeping track of the project to which you apply. In an ideal scenario, this template will have a number instead of having the project ID. Why? Because our goal is always to reuse what we create, if we associate our configuration with project A, we should create a copy of it to use in project B and follow the nomenclature at the same time.

In a similar way to the categories section, here it is valid to use the ALL option that would allow me to indicate that this is used for all projects in a category. In some clients, the categories even had various configurations but every new project had to start with the default configuration of the category, so the DFT option was also added to easily identify which one it was. As you begin to see, as we go deepern into the standard, we begin to have greater flexibility to identify what we are configuring without losing order and understanding the impact.

Template Number Section

By reaching this level of depth, we are entering configurations associated with the types of incidents. Under the same reuse criteria, our options here will only be numbers or the ALL option. Putting the name of the type of incident will only involve duplicating the information if we have to reuse something for more than one issue type, which would not scale and would be extremely difficult to maintain.

Tip: if the numbering of the issue type is one to one between the workflows, the screens and their schemes, you will make administration much easier. Since you will know that workflow 1 will always work fine with screen 1 and there will be no risk of breaking something in a project that could potentially be using a configuration that is not aligned in its numbering.

Particularly, when working with groups, this section is directly associated with the project role, so the nomenclature becomes an abbreviation of the corresponding role, such as ADM, DEV, USR as an example.

Action/Target Status Section

This section is only used at the Screens level since these allow a greater level of flexibility than other items to configure. Hence the valid options are the following

The last option on the list has certain restrictions in order not to abuse this type of screens. This nomenclature is reserved for global use screens, where all other parts of the name are cataloged as ALL and as a general rule, none of these screens should have more than 3 fields. Simply for a logical reason that the more options, the less likely it will actually be used for any issue type of any project on any category.

Enough theory so far, let's go to practical examples to see the nomenclature in action, just to simplify the examples, I will be grouping them under the type of configurations that accept the different levels of depth

Examples of configurations of field configuration schemes, issue type schemes, workflow schemes, issue type screen schemes, permissions scheme, notification scheme, issue security schemes or custom fields.

Examples of configurations for field configuration, screen schemes, workflows, custom fields, groups

Examples of screen configuration configurations

Bonus

In case you are interested in establishing your own standard and want to know the considerations to take into account when defining them and some of the most common errors when implementing them, I leave you a link to the episode of our podcast that we dedicate to this.

PS: You might need to learn spanish in the middle sorry :)

Do you have a different criterion to implement what is presented? Tell us in the comments

It is very common that there is more than one way to do things with Atlassian tools and we would love to discover other ways to solve them.

We hope you enjoyed reading,

Until the next time.