Just-in-time documentation:

A practical guide to agile documentation

bri hillmer | August 23, 2016

In my previous post, I discussed just-in-time documentation at a high-level. In this guide, I'll cover how I implemented JIT documentation at SurveyGizmo and provide you with tips on how you can JIT too!

Implementing JIT Documentation

My first step in implementing JIT documentation at SurveyGizmo was to find out 1) what users want to accomplish that 2) they cannot figure out on their own. I made a list of the below possible sources and ultimately decided to work with support tickets because we had a lot of them and it was easy to create a workflow around them.

  • Support Tickets
  • Feedback from Support/Sales Reps
  • Documentation Comments
  • Search Terms
  • Forums

Below is the just-in-time documentation workflow I created around our support tickets. It works like so:

  1. Before a support representative (a.k.a hero) responds to the customer, they ask themselves "Is this response generalizable?" Meaning, is this something that would help other users if it was documented?
  2. If the answer is "No," they submit their response to the customer and move on. If the answer is "Yes," they send it to me.
  3. I write a new document and send it back to the hero.
  4. If it's timely, the hero can send it to the customer in a later response that looks something like: "I passed your question on to our documentation team; they whipped up this document to help other users like yourself. Send us feedback if you have a moment!"

I leveraged several tools  in order to automate this process.


In Zendesk, our support ticketing software, I created a custom field called "Document This" that displays within each support ticket. Support heroes can simply check this box when they determine that their response should be documented.

2016-05-23_1536.png

Next, I used Zapier, a handy API integration tool, to set up an integration that looks for Zendesk tickets with "Document This" selected and sends the essential fields to Google Sheets.

2015-10-20_0851.png

This spreadsheet then became my just-in-time documentation to-do list. As you can see, it includes a link to the support ticket that I can click to read.

New documents based on JIT requests, were written as minimum viable product (MVP) documents.

Look! Another agile term!

Techopedia defines Minimum Viable Product (MVP) as "a development technique in which a new product or website is developed with sufficient features to satisfy early adopters. The final, complete set of features is only designed and developed after considering feedback from the product's initial users."

As applied to documentation, an MVP document has enough content to answer a customer's question.

Post-Writing Tasks

In all things agile, iteration is the key to success.  As such, I found that my job was not done once a JIT article is published. 

Letting Customers Know!

In order to give my new content the best chance of success, my next step after publishing an article was to communicate to customers that I was creating new content! In addition to looping the support team into the process so that they could communicate with customers, I also used two tools to call out new content in the knowledge base.

On the homepage of our knowledge base, I display a list of recently published articles complete with the date they were published. New visitors to our knowledge base can see straightaway that we're constantly creating content!

2016-05-24_0819.png

I also use article callout badges to alert users to new content.

2016-05-24_0815.png

Monitor Traffic

Because most of my new JIT content was made up of minimum-viable-product (MVP) articles I needed to vet the content. I found that monitoring traffic was a very efficient way to evaluate how my content was doing. It also gave me direction as far as which documents to iterate on and polish up.  

I used Google Analytics track traffic to my MVP documents. Based on the traffic, my next steps were to either unpublish low-traffic articles or polish up high-traffic articles.

Collect And Respond To Feedback

Finally, I collected and responded to customer feedback on all documentation. This almost always resulted in iterating on content in order to better answer customers' questions.

You Can JIT Document Too!

Are you ready to jump in and start just-in-time documentation? Great! Here are some tips to help you ensure JIT is a success at your organization.

Create A Workflow

In my experience evangelizing JIT documentation among my fellow documentarians[1], I've learned that most are already doing JIT documentation; they just haven't labeled it as such. If you are already doing this in a more informal way I recommend creating a systematic – ideally automated – workflow around creating documentation just in time.

Document it fast!

JIT requests should be high priority items. The key to getting repeated feedback from customers and support is to act quickly and give great customer service!

Be a JIT champion!

You don't have to call your workflow "just in time". You can call it whatever you want, however, there are advantages to giving your workflow a name and being a champion for it. Make sure you communicate what you are doing, why you are doing it, and how others can help. As your JIT workflow unfolds be sure to tout its success!


[1] http://www.writethedocs.org/documentarians/


About the author
bri hillmer
Bri Hillmer

is the Survey Sorceress/Documentation Coordinator at SurveyGizmo. An Ohioan at heart, bri wound up in Colorado by way of DC where she honed her skills in survey sorcery redesigning a fancy gubbermint survey that collected very crucial data on very weighty things. At SurveyGizmo she continues to use her powers of sorcery for good writing how-to documentation. Find her on Google+ and LinkedIn. Check out her documentation at: Help and Developer Resources

On the go? Bookmark this article for later with Ctlr + D
Subscribe and get notified as new articles arrive
(No spam, pinky promise)