> For the complete documentation index, see [llms.txt](https://help.swarmia.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.swarmia.com/settings/integrations/issue-trackers/jira/jira-best-practices.md).

# 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
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.