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
Below is the just-in-time documentation workflow I created around our support tickets. It works like so:
- 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?
- 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.
- I write a new document and send it back to the hero.
- 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.
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.
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.
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!
I also use article callout badges to alert users to new content.
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, 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!