I’ve just finished reading Practical Jira Administration by Matt Doar. The book is a collection of best practices from a Jira expert. It’s as if Matt sits you down by the fire and says, "Let me tell you what really matters about Jira". It’s the birds and the bees talk, for Jira.

Matt Doar is eminently qualified to write this book. He knows Jira inside out. He writes plugins to extend Jira functionality, runs a software tools consultancy called Consulting Toolsmiths, and is a frequent contributor to the Jira documentation wiki. The Atlassian technical writers, including me, think he’s an all-round good guy, not least because he took part in our recent doc sprints. Grab Matt for a chat if you see him around!

What is Jira?

Jira is an application developed by Atlassian to help people track issues and manage projects. It is a web application that you can download and install on your own server. If you prefer, you can use Atlassian’s software-as-a-service offering of Jira, which means that you get a Jira site hosted on Atlassian’s servers. People use Jira for various types of project, including software development, disaster management and help desks, to name just a few.


Highlights from the book

The book is easy to dip into. If you like, you can read the sections completely independently of each other. Matt has based the content on the questions that people ask him most often. Everyone will find something different in this book, depending on their use of Jira and the aspects that they are finding tricky. Here are some of the good things that struck me.

Notes. There are useful notes and warnings scattered throughout the book. Especially good are the notes in chapter 2 on the distinctions between the "Resolved" status, the "Resolution" field and the "Resolution Date" field. For example, on page 10 Matt writes:

Adding a resolution named "Unresolved" to the system Resolution field is a bad idea, because since the Resolution field now has a value, the issue will still be treated as resolved by the standard Jira gadgets.

Right now, you’re probably saying to yourself, "Huh, I didn’t think of that!" This book is full of that kind of moment.

Further reading. At the end of every chapter are some valuable pointers to the relevant pages in the Atlassian documentation, as well as useful plugins, books to read and people to contact.

Jira schemes. Chapter 3 tackles the complex notion of schemes in Jira. The overview on page 11 explains the concept:

A Jira scheme is a collection of configured values that can be used by more than one Jira project.

I like the way Matt has divided schemes into two sets, the simple and the complex. The three complex schemes depend on the issue type (page 17). That’s a good explanation to hang on to as you dive deeper into scheme configuration. I also like the practical guidelines Matt gives on managing and documenting your schemes (pages 21-3).

Site-wide and project-specific settings. It is useful to know which settings affect the whole Jira site, and which settings you can vary for each project. Matt gives a concise summary of just that distinction, on pages 25-6. The chapter, Jira as a Platform, goes on to show you how to configure Jira for an example project. The new project, requested by an accounting department, is very different from the existing projects on the Jira site. The accounting department wants custom field types, and needs to make some of the information visible to accounting team members only.

Workflows. Chapter 5 introduces workflows, one of the most useful features of Jira. After a brief overview, Matt gives a detailed description of how to design your own workflow from scratch. The idea is to build the workflow without copying it from Jira’s default workflow. Page 36 has some useful tips about why you would want to do that.

Remote access to Jira. Chapter 8 gives a succinct overview of the various methods you can use to access Jira data other than via the user interface: Email, SQL queries, SOAP API, REST API, XML, RSS feeds, and two command line interfaces.

Yes, and then chapter 9: Jiraargh! Frustrations. Matt describes some aspects of Jira that frustrate administrators, and some common problems that occur when administrators do not configure Jira properly. The best thing is the advice Matt gives on how to avoid such frustrations. It is all very practical, living up to the title of the book. For example, take a look at page 66, where the frustration under discussion is "The field’s description may be missing or misleading". Matt’s advice to administrators is:

Don’t accept a request for a new custom field unless it comes with a succinct and clear description of what the field is intended for. Then use that as the field’s description.


Two great Jira books in one month! Recently I posted a review of Jira 4 Essentials by Patrick Li. The two books complement each other very well. Patrick’s is a step-by-step guide to setting up your first Jira site. Matt’s book brings you all the best practices collected and refined by a Jira toolsmith of many years’ standing. If you think you know Jira, get Matt’s book: Practical Jira Administration, by Matthew B. Doar, June 2011. ISBN 978-1-4493-0541-3. Details are on the O’Reilly Media website.

Practical Jira Administration – a book by Matt Doar