Blog Archives

REST API documentation embedded in the application

Our development team has built a tool that documents an application’s REST APIs within the application itself. What’s more, you can test the REST resources and methods too. All from the application’s user interface. Now, that’s embedded help for nerds. 🙂 I’m writing this post because I think many technical writers and developers will be interested in this solution. It may trigger ideas about adding something similar to other applications too.

The tool is called the REST API Browser, and it is implemented as a plugin. At the moment, it is available only within the Atlassian Plugin SDK. In the future, you may be able to download the REST API Browser as a separate plugin and install it into any Atlassian application.

So, what does the REST API Browser do, what is the Atlassian Plugin SDK, and how can you get the REST API Browser to work within an Atlassian application?

Overview of the REST API Browser

This is what the REST API Browser looks like, when running inside an application called JIRA:

The /user/search REST resource in JIRA

JIRA is an issue tracker developed by Atlassian. The above screenshot shows one of the JIRA administration screens, part of the application’s user interface. I’m running JIRA on my local machine, in plugin development mode. The REST API Browser is available as one of the options on the application’s administration screens. It’s as simple as that.

In the screenshot, you can see the resources in the JIRA REST API, starting at the /user/search resource. For each resource, the REST API Browser shows the methods (GET, POST, PUT) and the parameters available.

You can even do real-time testing of the APIs, by submitting a request and seeing the response. In the screenshot below, I have run a GET request using the /user/search resource, asking for details of username “admin”. You can see:

  • A form, prompting you for the parameters relevant to the resource and method. In this case, the only parameter is the username.
  • The request, as formulated by the REST API Browser.
  • The response headers.
  • The JSON in the response body.

A REST request and response

The application’s REST APIs at your fingertips!

Which REST APIs does the Browser show?

The REST API Browser displays all the REST and JSON-RPC APIs available in the running installation of the application. That means all the remote APIs that are part of the application’s default installation (JIRA, in this case) as well as any additional REST APIs provided by a plugin.

So, if you install a plugin into JIRA, and that plugin exposes a REST API, the resources will show up in the REST API Browser too. Magic.

Introduction to Atlassian Plugin SDK

The Atlassian Plugin SDK is a tool for developers who want to create a plugin (add-on) for an Atlassian application. For example, you may want to add a new option to the Confluence page menu, showing all authors who have ever updated the current page. Or you may want to add a new option in JIRA that points to your organization’s intranet site.

But the SDK is useful even for people who don’t want to build a plugin. You can use the SDK to download and run an Atlassian application on your own machine, in plugin developer mode. One of the features that you get is the REST API Browser.

How can you get hold of such sweetness?

Here’s a quick start guide. First, install the SDK and use it to download and run your application:

  1. Follow the guide to installing the Atlassian Plugin SDK. Do just steps 1, 2 and 3. You can skip the last step, which sets up an IDE (Eclipse, IDEA or NetBeans), if you do not need a development environment.
  2. Create a directory in your file system to store the application executables. Let’s assume you want to run the REST API Browser in JIRA. Then, for example, you could create a directory called myjira.
  3. Open a command window.
  4. Go to the new directory that you just created, myjira.
  5. Run atlas-run-standalone --product APPLICATION. For example, atlas-run-standalone --product jira.
    Note:
    There are two dashes in front of the word product.

After following the above steps, you will have the application running on your computer. When all the downloads and installation are complete (which may take a while), you will see a message in your command window that includes the URL for the local installation of the application.

For JIRA, the message will look something like this:

[INFO] jira started successfully in 174s at http://localhost:2990/jira
[INFO] Type CTRL-D to shutdown gracefully
[INFO] Type CTRL-C to exit

Now you can access the application in your browser and use the REST API Browser from the application user interface:

  1. Go to your web browser and enter the URL given for your application. For example, http://localhost:2990/jira.
  2. Enter the username and password: admin / admin.
  3. Go to the application’s administration screen. For example, in JIRA: Click Administration at top right of the screen.
  4. Click REST API Browser on the administration screen.
  5. Choose an API from the dropdown list at the top left of the screen.
  6. Choose a resource from the list on the left of the screen.
  7. See the methods (GET, POST, PUT, etc) and the parameters available for that resource.
  8. To test the resource, enter the parameter values as prompted then click Execute.

The documentation has the details of running the REST API Browser in the SDK, and of viewing and testing the resources.

Getting technical: How the REST API Browser works

The source code is available on Bitbucket, as part of the Atlassian Developer Toolbox. The developer’s guide describes how to ensure that a REST API is included in the Remote API Browser. That document also gives a summary of how the browser is put together.

Pretty neat, huh

From a plugin developer’s point of view, the REST API Browser is very useful. From a technical writer’s point of view, I think it’s pretty revolutionary. Has anyone seen other examples of embedded REST API documentation?

Kudos to Rich Manalang and the Atlassian developer relations team for developing this shiny tool. Here is the blog post in which Rich announced it: Introducing the REST API Browser and the Atlassian Developer Toolbox.

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. 😉

Book review – JIRA 4 Essentials

Book review - JIRA 4 EssentialsI 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. 🙂

Book revew - JIRA 4 EssentialsThe 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.

Other highlights

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.

Summary

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

JIRA 4 Essentials, by Patrick Li, published by Packt Publishing Ltd in May 2011. ISBN 978-1-849681-72-9. You can get it at Amazon.com.

Congratulations on a job well done, Patrick. 🙂

JIRA cloning to create a template for repeated documentation tasks

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:

JIRA cloning

A JIRA issue used as a template

Below is a list of all the subtasks on the above issue. We will use each of the subtasks as a template too:

JIRA cloning

The subtasks on our JIRA template issue

This is an example of one of the subtasks:

JIRA cloning

A JIRA subtask to be used as a template

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. 😉

Badges for Twitter tips and thanks to technical writers

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.

The badges are oh so cute. Vijayendra Darode came up with the idea and posted a comment on my earlier blog post:

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:

Badges for Twitter tips and thanks to tech writers Badges for Twitter tips and thanks to tech writers

(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:

Badges for Twitter tips and thanks to technical writers

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!

%d bloggers like this: