Two 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.
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. 😉
I have just finished reading the book JIRA 4 Essentials by Patrick Li. It is a very useful quick-start guide to Atlassian JIRA for administrators. I think you will also find it interesting if you are a JIRA user without administrative powers, because it shows you how to set up your own JIRA site. You can even run JIRA on your PC. Imagine using your own tame JIRA to learn what goes on behind the scenes and see what power those administrators really have!
Patrick Li is co-founder of AppFusions, an engineering consultancy specialising in connectors, solutions and the integration of Atlassian applications with other products. As well as being co-founder, Patrick is a senior engineer at AppFusions and has worked with Atlassian applications over the last four years. I’m impressed that he has managed so successfully to distill his extensive knowledge into this step-by-step guide to JIRA administration.
What is JIRA?
JIRA is Atlassian’s tool for issue tracking and project management. 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. Whichever way you do it, your team can use JIRA to manage their tasks, issues and projects. People use JIRA for various types of project, including software development, disaster management and help desks, to name just a few.
First impressions of the book
The book has a pleasing format and a professional layout. I like the strong contrast in the size of the headings in comparison with the text. There’s more good contrast in the serif typeface for the text and a nice clear sans serif for the headings. The many screenshots, tables and “how to” sections break up the content nicely. The layout gave me a feeling of confidence that this book knows what it’s talking about. 🙂
The picture on the front cover caught my eye. It shows a set of large metal rings on a playground. The ring in the foreground has a number of balls hovering over it, surrounding a smaller ring. It reminds me of the JIRA logo. I guess that’s intentional.
Exploring the book and learning about JIRA screens
While browsing through the overview (pages 1-2) I learned something new immediately: You can design your own screens in JIRA. It’s obvious now I know about it, but as a JIRA user I have never had to do that. It is something the administrators do. So I hopped directly into chapter 5 (Screen Management) and learned all about it.
The chapter starts with a good introduction, telling me exactly what a screen is and why I would want to create one in JIRA. I liked the turn of phrase on page 137:
Creating a new screen is like getting a blank piece of paper, the fun part is to add and arrange the fields on the screen.
There is an interesting tip on page 139, about removing required fields. Evidently JIRA does not prevent you from deleting fields that it may need later on, such as the issue summary. This sort of tip is invaluable to administrators just starting out with the product.
The instructions and screenshots focus on JIRA 4.2. The team at Packt Publishing are planning an update towards the end of this year.
There are a few typographical errors scattered here and there that spoil the flow a bit. Even so, this book is a very good read. Patrick takes you by the hand and leads you through the concepts you need to understand and the tasks you need to complete.
There are many many useful sections in the book. These are just a few of the highlights.
Installation: Pages 13-30 give a very thorough, authoritative and clear guide to installing and configuring JIRA. As you go through the book, you will follow the instructions in each chapter to set up your own JIRA site. By the end of the book, you will have a sample “help desk” project. For example, pages 59-65 lead you through the essential parts of setting up the project in JIRA.
JIRA data hierarchy: Pages 31-2 contain a useful analysis of key parts in the JIRA data model: Projects, issues and fields.
Schemes: Take a look at pages 56-9 for an overview of JIRA’s schemes. Patrick provides a neat description of what a scheme is:
A scheme can be thought of as a template or collection of configurations. Once we have created a set of configurations such as permissions, we can save that as a scheme (known as Permission Scheme) and this can be reused and applied to multiple projects.
Screen schemes: After telling you about the simpler parts of screen creation, Patrick introduces screen schemes (page 143). There is a good explanation of why you would use different screens for each operation on an issue (create, edit, view).
Workflows: There is a solid chapter on workflows, one of JIRA’s most powerful and flexible features. See the useful tips about importing and exporting workflows on pages 168-70.
Gadget colours: Did you know that administrators can define the set of colours that users can choose for their gadgets? I didn’t know that. On page 299, Patrick describes the “Gadget Colours” part of JIRA’s “Look and Feel Configuration” screen.
As a JIRA user I’m well used to creating issues, searching the issues in a project, having issues assigned to me and working on them. I have not played much at designing my own JIRA project or JIRA site. Reading Patrick’s book has given me a good insight into the power and flexibility of the application. I recommend it if you want to know more about what goes on behind the scenes and the way that your JIRA administrators can customise the projects, issues and screens.
For JIRA administrators I think the book does a great job of leading you through the configuration of a project, reducing the complexity to a series of easy-to-follow steps.
Another book has recently appeared: Matt Doar’s Practical JIRA Administration. I have not read it yet, but I have seen snippets in reviews. I think the two books will complement each other very well. Patrick’s book leads you through the initial setup of your JIRA site and project. Then Matt’s gives more advanced tips and techniques.
The details of Patrick Li’s book
Congratulations on a job well done, Patrick. 🙂
At each major release of the software that we document, a technical writer has to perform a number of tasks. Many of the tasks are repeated at every release. My team uses JIRA to keep track of our documentation tasks. Last week I decided to try using JIRA’s cloning functionality to create a template, consisting of an umbrella issue with a set of subtasks, that we can clone for future releases. It’s looking like a useful idea, so I’m blogging about it in case other people find it helpful too.
JIRA is a bug-tracking and project management tool. Up to now, when preparing for a release we’ve created the documentation tasks in JIRA by basing them on the tasks from the previous release. This worked well, but we did spend a fair bit of time sorting out which tasks were required for every release, as opposed to the feature-related documentation bound to a specific release. We also had to remove comments like “Completed this task on Monday 1 April,” or “Reviewed by PM and dev.”
What is JIRA cloning?
In JIRA, you can clone an issue (task) to create a copy of the useful parts of that issue. When you clone the issue, JIRA creates a new issue with the same summary (title) and description as the one you’ve cloned. It copies across the information from other relevant fields and sets the status of the new issue to “open”. The JIRA documentation lists all the fields that are copied to your new issue.
You can also choose to clone the subtasks — and that’s where it gets really handy!
Creating the template for documentation tasks
To create my template for use in future releases, I cloned my documentation task from the previous major release plus all its subtasks.
Then I deleted the subtasks that related specifically to the past release. I was left with an umbrella issue and a number of subtasks, one for each of the tasks that need to be done at every release.
Next I adjusted the issue summaries and descriptions to make them generic, so that they no longer refer to any specific release number.
Now that we have a template that other technical writers will be using, I decided to expand the descriptions too. It’s useful to include a bit more explanation than I have done in the past, when the descriptions were mostly just a reminder to myself of what needed doing.
Here’s that our umbrella template issue looks like now. The product I’m documenting is called “Confluence” and I’m using the convention “x.x” to indicate a release number that needs to be filled in when we create a real issue based on the template:
Below is a list of all the subtasks on the above issue. We will use each of the subtasks as a template too:
This is an example of one of the subtasks:
As you can see, the subtask contains quite a bit of detail about what needs to be done.
You’ve probably also noticed that all the issues have a status of “Resolved”. I did that just so that the template issues don’t keep popping up and demanding to be addressed. But when we clone the issues at our next major release, JIRA will automatically give the new issues a status of “Open”.
Using cloning to prepare the documentation tasks at our next release
At the next major release, we can just clone our umbrella template issue and say “Yes, please” when JIRA asks if we want to clone the subtasks too.
We will then go on to add more subtasks to our new issue. They will be the tasks specific to the release, such as documenting new features and changes to supported platforms. The template issues will remain untouched, ready to be cloned again next time round.
No doubt we will find tasks and improvements to add to our template issues from time to time as well.
The benefits of having a task template
This will save us a lot of time: A couple of hours per release!
The template will help us make sure that we don’t forget any of the things that need to happen at each release. It will also give new team members a concise overview of what’s involved in a documentation release.
The template also gives the product managers and development team a good insight into the tasks that the technical writers need to do in order to publish and maintain the documentation. Many of the repeated tasks revolve around ensuring that we have version-specific documentation for customers who do not upgrade to the latest release, supplying downloadable versions of the documentation for customers who cannot use our online documentation, updating the tutorials that are shipped within the product itself, and generally keeping the documentation ticking along.
It’s not uncommon for people, other than the technical writers, to overlook this sort of necessary but behind-the-scenes task. 😉
It’s recently struck me again: There is so much creativity, generosity and enthusiasm in the technical writing community! A while ago, I let people know that I was kicking off a project called Tips via Twitter. Many technical writers commented and tweeted their encouragement and ideas. Now we’ve just started a Twitter tips stream for another of our products, and designed badges that tweeters can display on their blogs.
To encourage users to tweet tips, I would consider giving them a badge of honour which they can proudly display on their blogs or any social networking site. A badge which says “I share my Tips via Twitter. Do you?” or something similar.
Thank you so much Jay! Here’s what the badges look like:
(If you want one for your blog, grab the HTML from my Atlassian blog post.)
Highlighting the fact that people can contribute to the documentation
Larry Kunz had another great idea, that we should make the community aspects of our documentation more visible. So I’ve been creating pages called “Contributing to the xxx documentation”, where “xxx” is the product name. For example, here’s the page for our JIRA bug tracker: Contributing to the JIRA documentation, and for the Confluence wiki: Contributing to the Confluence documentation.
The “Tips via Twitter” pages are now children of those pages, and so are the “Tips of the Trade” pages, where we link out to “how to” blog posts by our customers and community.
What’s more, we now have a shiny new button in the page footers, directing people to the page about contributing to the documentation:
Thank you to the technical writing community
Innovation, passion and generosity are alive and well amongst technical writers. Thank you everyone! I’ve also added a paragraph in the Atlassian blog post, letting people know that the technical writing community rocks!