Just-in-time documentation: Employing agile methodology in documentation

What Is Agile?

"Agile" is a very popular buzzword. Use "agile" as an adjective for whatever you are doing and you'll get some traction: agile software development, agile marketing, heck, emotional agility^[1] is a thing! Unlike some buzzwords, though, the popularity of the word "agile" is not unfounded.

The Agile Manifesto^[2] turned some long-standing assumptions of project management on their heads. Agilists value "individuals and interactions over processes and tools, working software over comprehensive documentation, customer collaboration over contract negotiation, responding to change over following a plan.

How about that point about agilists valuing working software over comprehensive documentation? As a documentarian^[3] this had me questioning my role as a technical writer in agile Software-As-A-Service (SAAS) organization. Fortunately, instead of polishing my resume I chose to use our development team as inspiration!

Abandoning Just-In-Case Documentation

Don't worry, I'm not as annoyingly optimistic as that sounded. It was only after evaluating the challenges with our existing knowledge base that I was really inspired. In 2014 I became the one-person team in charge of the documentation at SurveyGizmo. Our existing knowledge base was stale and didn't do a great job helping people achieve what they were looking to do.

I knew that in order to make SurveyGizmo's documentation successful I needed to find a way to quickly convey to users that someone was behind the scenes, full time, creating content. I wanted it to be apparent to users that we were creating content daily based on users' actual questions.

I also decided to abandon our just-in-case approach to documentation. Our knowledge base was almost entirely made up of guides to our various features that were written from a just-in-case perspective. That is, the documentation was written before the feature was released with a theoretical user in mind. In so doing we had to try to anticipate the questions actual users would have. Turns out, we're actually pretty bad at doing this.

Not to mention, feature guides are difficult to use. First, they require that user is familiar with your terminology in order to search and find the correct article. Second, they're pretty cognitively taxing. They usually require users to read the document more than once; first, in order to determine if they've found the correct feature and second, to apply it to their task.

Just-In-Time Documentation

With these challenges in mind and the agile methodology as my inspiration, I started Just-In-Time (JIT) Documentation. Just in time is actually a production strategy, used primarily in manufacturing, to cost-effectively manage inventory supply. Some say that the approach originated in Japan, others credit Henry Ford. In Just-in-time manufacturing rather than warehousing parts, manufacturers wait to produce the part once the customer orders it, just in time!

As applied to documentation, just in time means that we create just enough documentation, just in time.

The feature guides that we typically create when writing just-in-case documentation usually cover what the software can do. In just in time, we wait for feedback from customers to determine what content we will write. The result is that we focus on 1) what users are actually trying to accomplish that 2) they cannot figure out on their own. This is just-in-time documentation!

JIT Document Types

Four just-in-time document types emerged out of writing content just in time.

Buried-in-the-UI Documents

These are short articles that help users find a feature or tool that is buried in the user interface. For example, "Change 'Comments' Text" and "Remove Page Breaks" are two high-traffic, JIT articles that cover features that are buried in the UI.

How-Do-I Documents

How-do-I articles cover how to achieve multi-step tasks. For example, "Creating a Diary Survey" and "Creating a Pre-Test/Post-Test Survey."

FAQ Documents

These are short articles that address frequently asked questions usually about unexpected results or behaviors. For example, "Required Questions Left Unanswered In Complete Responses" and "Why Can't I See My Survey Changes?"

Workaround Documents

Finally, workaround articles document methods for achieving functionality that is not available as a built-in feature in the application. For example, "Send a Text Message From Your Survey" and "Send a Reminder to Partial Survey Respondents" are both tasks that SurveyGizmo was not designed to do but can be accomplished in SurveyGizmo with a little ingenuity.

Documenting workarounds was the most surprising philosophical shift that came about as a result of shifting focus from just-in-case documentation to just-in-time documentation. The fact that users wanted to achieve tasks that were not available as part of the core application was not really even on my radar until I started doing JIT; it was certainly not something that I thought was under my purview. As a result, if we return to the Venn Diagram, JIT documentation became anything that customers wanted to accomplish that they couldn't figure out on their own.

Does JIT Work?

How do we know just-in-time documentation works? There are few ways to measure success.

First,  unique sessions (a proxy for visitors) to our help site by 37% post-JIT.

Second, the number of pageviews per session decreased post-JIT. Only in documentation is fewer page views a good thing! I’m making a bit of a leap here but choose to interpret this to mean that users are getting to an article that answers in fewer clicks.

Time spent on page increased post-JIT. We consider pageviews of 2 minutes or longer to be a quality view. Quality views indicate that the reader is consuming the content and, hopefully, getting the answer to their question. Paired with the decrease in pageviews per session it is probably a pretty safe assumption that users are getting to an article that answers their question.

Finally, I think the most powerful evidence that JIT is working is anecdotal. We receive comments like those below from an article that covers a simple customization: hiding page titles from displaying in your survey. The content for something like this under the just-in-case philosophy of documenting would have been covered in a larger article about the overall styling options or, perhaps, not at all.

In JIT this kind of content makes up a large percentage of your knowledge base. What a big win for JIT!

What I've Learned After Two Years of JIT

It’s OK To Have A LOT Of Content

Prior to JIT I worried about having too much content.

I worried about what it meant to keep it up to date. What I've learned is that documentation can be updated just in time too! Worst case scenario? A customer finds some navigation steps that are a touch out of date. If this trips them up, they'll let you know. And you can fix it straight away and let them know. What a great opportunity to wow your customers!

I worried about how difficult it would be to browse through the knowledge base. I've learned that an overwhelming majority of users search for their answer rather than browsing so I don't need to worry about the amount of content in our knowledge base

It's OK To Document Workarounds

Probably the most interesting result of the shift to JIT is documenting workarounds. If you have fully tested the workaround and you document it as such; then documenting workarounds that allow users to achieve out-of-the-box customizations is great customer service!

Check out my practical guide on how you can JIT too!