Book review – Practical JIRA Administration by Matt Doar

Book review - Practical JIRA AdministrationTwo great JIRA books in one month! I’ve just finished reading Practical JIRA Administration by Matt Doar. 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.

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 Atlassian documentation wiki. Matt and I have bumped into each other a few times, in the flesh and on various wikis and forums. He is an all-round good guy. He drops nice comments on our documentation and took part in our recent doc sprints, where he dubbed himself Matt “Galaxy” Doar.

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.

Practical JIRA Administration, the book

The book is published by O’Reilly Media, so of course it has a creature on the cover. Matt’s book got the chickens! These particular birds are Cochin chickens (Gallus domesticus) as the book’s colophon informs us. Nice. There’s a forward by the two Atlassian CEOs, Scott Farquhar and Mike Cannon-Brookes. Three of the technical reviewers are Atlassians, and one is an Atlassian partner.

The book is easy to dip into. If you like, you can read the sections completely independently of each other. Dive straight into the one you need. Matt has based the content on the questions that people ask him most often. The information applies to JIRA version 4.2.4, which Matt specifies nice and clearly on page xi.

I love the title of the last chapter: Jiraargh! Frustrations 🙂

Highlights for me

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.

Hints and warnings. There are notes scattered throughout the book. For example, chapter 2 pinpoints the distinction between the “Resolved” status, the “Resolution” field and the “Resolution Date” field:

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!” The book is full of that kind of moment.

Further reading. A section at the end of every chapter points to the relevant pages in the Atlassian documentation, useful plugins, books to read and people to contact. These are valuable pointers.

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 us how to configure JIRA for an example project: a project that is very different from the existing project on the supposed example JIRA site. Matt’s example is an accounting department that needs custom field types and wants 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 designing 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. In this chapter Matt’s JIRA expertise really shines.

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 on the database, 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 that Matt gives advice 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.

Book details

Practical JIRA Administration, by Matthew B. Doar, June 2011. ISBN 978-1-4493-0541-3. Details are on the O’Reilly Media website.

TL;DR: The book is a carefully compiled 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!

OT: Hey Matt, you can buy chocolate Galaxy pie at the Chocolate Room in Sydney. Just letting you know. 😉

About Sarah Maddox

Technical writer, author and blogger in Sydney

Posted on 5 July 2011, in atlassian, technical writing and tagged , , , . Bookmark the permalink. Leave a comment.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.

%d bloggers like this: