The tech-writer’s journal #2 — Just-in-time documentation
Hey there!
In this article, I am attempting to explain the two popular types of tech-documentation — The traditional and the just-in-time documentation.
I stumbled upon this topic when listening to the third episode of Not-Boring Tech Writer by Jacob Moses. The podcast was quite intriguing, and I wanted to share glimpses of it in our tech writer’s journal. We discussed in the last post how the field of tech-writing has evolved from brochures to webpages. The leap from conventional to just-in-time documentation may be found close.
The Traditional Documentation
Traditional documentation involves a manual-style feature guide that outlines the functionality of a product. It has its positives and drawbacks. Traditional style documentation is certainly important for the knowledge base, but it is difficult to use for the end-user to solve a specific problem, since finding solutions through this type of documentation often requires familiarity with the product’s terminology.
Consider that you have a document to add employee details. The name of the document would most probably be “Add employees.” It will include all the specifics of the functionality, the credentials you would require to access the feature, the errors that you might encounter, and so on. This single document should be equipped enough to solve any questions that might come up when a user tries to add an employee. Here, we are not sure what precisely the customers want. We are simply assuming that this could be what they want and building documents around that assumption. This type of documentation is fully useful only for a specific set of target audience. For instance, users who are new, and are trying to weigh the product based on the features available.
Traditional documents are undoubtedly vital for a product, but often users find it difficult to navigate through them and find the solutions to their problems. Thus, we have just-in-time style documentation.
Just-in-time Documentation
Just-in-time documentation involves creating task-oriented documents that resolve a specific problem as and when you receive support-tickets. It would serve as a perfect supplement to the traditional feature-guide. Here, instead of concentrating on what the software can do, you concentrate on what users want to accomplish.
For instance, consider that a user wants receive an email alert whenever there is a survey response. Now, say you have a traditional document in place that explains how to set up email alerts. There is a good chance that the reader might go through the whole document, and think whether this solves what he is trying to accomplish. In contrary to this, in just-in-time documentation, you can have a document named “How to get email alerts whenever there is a survey response?” that has a tailor-made solution. Thus, saving both time and effort.
Along with this, there is an additional layer to the just-in-time documentation. Ideally, we hand-out help manuals and guides for features and processes that the users cannot figure out themselves. There are many UI/UX developers working on a particular product to improve its usability. So, there is no need to create documentation and how-tos for all the actions that a user can accomplish using a product. The need for documentation arises when a user gets stuck in the process of achieving a particular goal or when there is a process that they cannot figure out on their own, and that is where just-in-time documents come in handy.
a. Taking cues for just-in-time documentation
Just-in-time documents in their purest form are generalized solutions to support-tickets. The starting point for any just-in-time document would be a support ticket. If the support agent feels the solution to the ticket can be generalized and re-used, the solution transforms into a just-in-time document.
b. Customer-driven knowledge base
Usually, the problem with documentation is the lack of connection between the user and the document. Be it the user not being able to find what he/she wants, or finding outdated/irrelevant content. Just-in-time documentation effectively fills this gap between the user and the knowledge base especially, since most of the content is driven by the users themselves.
To conclude, at the end of the day, all we are trying to do is to make customers’ lives easier. Just-in-time documentation not only delivers straightforward solutions, but also is a great way to convey to your customers how important they are to your business.
In our next post, we shall discuss “Writing Inclusive Documentation”.
Leave your thoughts on this in the comment section below.
References
- “The Not-Boring Tech Writer” podcast by Jacob Moses (in conversation with Bri Hillmer)
