# Best practices

## **Jira projects**

Create one Jira project per team. This is also what Atlassian recommends.

If that's not possible, use a Custom Field to assign issues to teams.

## **Issue types**

Use a hierarchical structure for roadmap work. For example, Epic -> Story -> Sub-task.

Outside of the hierarchy, you'll likely have Bugs and Tasks.

Teams can create their own issue types.

## **Workflow statuses**

Teams can customize their workflows as they want. It's good to start from a standard To Do -> In Progress -> Done, but it's common to add your own steps. You can normalize across statuses in the Swarmia settings to account for how teams work.

## **Labels**

Use labels to automatically sort work, rules can be adjusted and manually overridden in Swarmia as needed. For someone using the [Balance framework](https://www.swarmia.com/blog/balancing-engineering-investments/), this could be New things, Existing things, Productivity, and KTLO (Keeping The Lights On).

## Configuring Swarmia

Swarmia's [Jira mapping](https://help.swarmia.com/configure-jira-organization-settings) will convert complex workflow statuses and issue types into a simplified model. We will also map projects to teams and user identities between different systems.

These best practices allow you to create a simplified [Investment Category configuration](https://help.swarmia.com/configuring-investment-categories):

* Epics and Stories go to New Things by default
* Bugs and Tasks go to Keeping The Lights On
* Labels can be used to categorize more granularly, for example categorizing a Story as Improving Productivity.

Please don't worry if these practices aren't used across all teams. Swarmia makes team-specific customizations very easy.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://help.swarmia.com/settings/integrations/issue-trackers/jira/jira-best-practices.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.