Just in time documentation – some pros and cons

Bri Hillmer has written two articles on Just-In-Time documentation (https://www.knowledgeowl.com/home/just-in-time-documentation-a-practical-guide and  https://www.knowledgeowl.com/home/just-in-time-documentation). This is an alternative to what she called Just-In-Case documentation. The idea is you write topics that answer real world queries users ask the Support team. This rather than writing a comprehensive user guide, just in case someone wants to know about topic X or topic Y.

This approach focuses on user needs, answering the questions user have. It also provides users with worked examples, each one aimed at solving a particular scenario. In a complex environment, users may need to combine a set of functions or features in order to solve their problems. Sometimes a topic-based approach doesn’t provide that type of information. Just-In-Time documentation could help users understand individual features and how to combine them. And it may be that 80% of the queries relate to 20% of the product’s functionality.

However, this approach does require the technical authoring team to be able to turn around these articles quickly enough. It’s likely that similar topics will come up a regular basis, so there also needs to be a way to reuse some passages of text, in order for the Technical Authors to work in an efficient manner. Also, there might be a legal requirement to provide a comprehensive guide.

Is this an approach you have used? If so, please share your experiences, using the comments box below.

New note-taking methods for technical communicators

Note-taking is an important part of a technical communication process. A typical project can move from the account manager to the project manager, and then onto the technical communicator.  Sharing information gathered at client meetings with project team members is often done through internal meetings and phone calls, handover documents written in Word, and other related files uploaded to a SharePoint folder. This type of approach works, but it can be slow and time-consuming.

There are some new(ish) note-taking approaches for students that might also work for technical communicators. We’ve described them below.

Reusable notebooks

The Rocketbook Wave and the upcoming Everlast Notebook are reusable paper notebooks where you transfer your notes into the Cloud using your smartphone. Both notebooks work by you using Pilot FriXion pens. In the case of the Rocketbook Wave, you can erase your notes using your microwave oven (or hairdryer) and reuse the notebook. With the Everlast, erasing is done using a damp cloth.

Everlast notebook

While notebook costs and storage issues are important to students, they are unlikely to be of much concern to technical communicators. You could use the same note-taking system, but with different “hardware”.

The “Bullet Journal” method of note-taking

The Rocketbook notebooks contain dotted paper pages, similar to the Leuchtturm 1917 dotted notebooks, and they are often used in conjunction with the Bullet Journal method of note-taking:

We’ve yet to test the Bullet Journal method, but it might mean that it’s possible for others to read handwritten notes and reduce the need to transcribe them into written notes.

Transferring your notes into the Cloud

There are three popular Cloud storage systems for note-taking: Evernote, Microsoft OneNote and Google Keep. You can use your smartphone to scan your notes and upload them as images to the Cloud. The dotted paper notebooks, such as the Leuchtturm 1917, should improve the scanning image quality.

You can organise your notes into electronic notebooks within these applications, and also add tags to add metadata (See I’ve Been Using Evernote All Wrong. Here’s Why It’s Actually Amazing).

Into those online notebooks, you can also clip web pages and insert files, such as Word documents. It’s never easy to get everyone to use a new application, so OneNote has the advantage of being part of the Office 365 suite and easily integrated with SharePoint. Unfortunately, custom tags can’t be created currently in OneNote for Mac, and this may be an issue for some users.

Which methods do you use?

Please about share your ideas and suggestions below.

Being Agile in technical documentation – Part two

Two years ago, we wrote a number of posts, and an Adobe-sponsored whitepaper, on Agile and its effects on technical communication. This topic was picked by others, including Sarah O’Keefe and Mattias Sander, who made further suggestions. We thought it was time to revisit this topic, and expand on some of the issues raised.

In Part one, we looked at Agile and the Lean method’s principles of maximising value and minimising waste. Here in Part two, we look at how we can minimise waste in the document production process.

Removing waste from user’s interaction with the product

Let’s briefly touch on value and waste during the use of the product by the user.

User Assistance can contribute to the user being less “wasteful” when they’re using the product: minimising the time having to stop when they get stuck, or having to rework things to fix mistakes. This means you need to provide the right information at the right time, in the right place, and in the right format.

It needs to provide the required information to the reader as fast as possible. In practice, this can mean having the Help embedded in the application itself. It might also mean creating different documents to suit different audiences, or even personalised content. It also implies User Assistance needs to be as short as possible, but not shorter.

This also means you’ll need to carry out some usability testing of the content and perhaps even A/B testing. You have to test to check what you’re producing is what gives value to users.

Removing waste from user documentation process

Let’s look at how we could apply Lean principles to writing technical documentation in an Agile environment.

Is it needed?

The Lean approach can help us identify which parts to document, and which to leave out. Under Lean, you should only document what customers tell you is absolutely necessary. Only information that adds value to the user, or increases their productivity, should be included. If the information isn’t needed by anyone, we shouldn’t write it (unless we have to do it for legal or other reasons).

By going through a design process of empathy, defining needs, generating ideas, prototyping and testing, we can identify the best way to solve a specific problem. In practice, User Assistance (in other words, the online Help and user documentation) should be considered part of the product design, and included in the initial design planning, rather than being left to the end. This requires a change in product planning thinking, as documentation is often treated as an afterthought, pushed to the end of the development process.

In an Agile development process, designers will create Use Cases for each feature, and technical communicators can do something similar. Use Cases can be used in the planning of User Assistance to identify who will use it (the audience), what value it will provide (or what problem it will solve), and when they will use it.

Load levelling

In addition to the waste of “non-value adding work”, in our simplified description of Lean there are also wastes of “overburden” and “unevenness”. These relate to having too much work to do in the timescales allowed, and having to stop and wait for something you need in order to carry on working. Instead, our goal is to have a consistent, productive rhythm to our work.

For technical communicators, this “overburden” and “unevenness” could be waiting for reviews, waiting for edits, waiting for work, or waiting for approvals. It can also mean wasting time having to switch tools or stop and start different tasks. If we can measure these wastes, we can justify the need to change working practices.

Levelling allows a consistent workflow, which makes it possible to set standards and identify abnormalities. The Lean methodology contains a number of techniques for smoothing out a work schedule, such as a triage approach to prioritising new work requests. One of the key ways we can level the technical writing workload is simply to start the project earlier. The benefits from avoiding having to stop and start, or rush things at the end, may outweigh any waste from having to go back and amend some of the content written at the start of the project.

One-piece flow

Related to load levelling is continuous, or one-piece, flow. W. Edwards Deming proved in the 1950s that implementing a continuous flow system, instead of working in batches, can have a significant impact on improving quality and reducing throughput time.

A continuous flow system works like serving people food from a counter. Customers move forward, picking up their stater, main course and pudding as they go down the line. When a serving station runs out of food, there should be a new tray of supplies ready to replenish it just in time to serve the next customer. People only work on one piece at a time and only one piece of work moves from one stage to the next.

Deming proved one-piece flow results in fewer bottlenecks, less waiting and faster throughput. You pull work from the previous step when you have available resources. It also means that mistakes appear earlier. As items are pulled one piece at a time, you should have one only faulty item to deal with, rather than a large batch of defects. If you fix the problem, identifying what caused it, it goes away before it can escalate.

One example of technical communicators working in batches is when they send out drafts of whole manuals to reviewers. One piece flow could mean passing on content for review in smaller pieces – perhaps even issuing content for review on a daily basis, making it an integral part of the product development process.


One of the tools used in both Lean and Agile projects is a Kanban board. This is a visual representation of the pieces flowing through the process. It can help the team identify any problems, and control and regulate the amount of new tasks given to the team. It can be the case that no new work is added to the board until a current work piece is defined as “done”.

One approach is to include the technical writing task in the project Kanban board. This could mean if there are problems with creating documentation, these are brought to the surface for fixing there and then.

Alerting and fixing any problems early

The philosophy of both Lean and Agile is to bring problems and defects to the front, and force people to confront them and fix the immediate and underlying problems.

Within Lean, and often in Agile, when a problem or issue is identified, everyone is empowered to stop the process, and swarm around the problem to solve it immediately. So could a technical communicator have the right to flag to stop the process? Would a development team be willing to face up to the sheer amount of documentation and work with the technical communicator to tackle the problem? The answer should be yes, but it would depend on how closely the team adheres to Agile principles. For this to happen, the team needs to have an authoring system that enables non-professional technical communicators (such as developers) to be able to contribute content.

Dealing with variations in project plans

Technical communicators need to avoid having to pull the emergency cord, and this means they need to be able to deal with some of the variations that can arise as projects change over time.

In Part three

In Part three of this series, we’ll look at how we can modify our writing process and tools so we can implement these approaches into how we work.

Being Agile in technical documentation – Part one

Two years ago, we wrote a number of posts, and an Adobe-sponsored whitepaper, on Agile and its effects on technical communication. This topic was picked by others, including Sarah O’Keefe and Mattias Sander, who made further suggestions. We thought it was time to revisit this topic, and expand on some of the issues raised.

This is part one of a series of posts on this topic. 

Being Agile in technical documentation – Part one

Agile creates a number of challenges for technical communicators, which can mean they need to adapt their working methods in order to work efficiently.

What is Agile?

Agile development is a way of managing IT development teams and projects that has been around since 2001. It’s an alternative to traditional project methods, which, it was felt, often lead to unsuccessful projects.

One of the main criticisms of traditional project management methods was they often led to teams working to a plan that became less relevant to user needs, current technology, and market trends over the lifetime of a project. This could result in software that were already out of date by the time it was released. The approach was also criticised because some faults might not be identified until towards the end of the project, which could make fixing them time-consuming and expensive.

In 2001, a group of developers published the Agile Manifesto, which outlined their vision of how they felt software projects should be run.

In Agile projects, the goal is to develop robust products quickly. The project and its deliverables are typically broken down into short development cycles, which are usually two weeks, and, based on the feedback and lessons learnt from these cycles, the project adapts and changes over time. The team delivers early, frequent and continuous releases of products.

One goal is for teams to find problems quickly, and either correct a problem immediately or eliminate the affected feature altogether. This should mean there is less waste, something we’ll look at in more detail later.

Agile’s effect on writing

In traditional project environments, technical communicators often use functional specification documents, which describe what will be delivered, and any available prototypes, as their information source. At the start of the project, they have detailed information on what the product is meant to do.

The Agile manifesto proposes working software over comprehensive specification documentation, which often means there is far less written information for technical communicators to use. They often have to produce content based on word-of-mouth descriptions, fluid sketches, use cases, and business cases.

Managing Agile projects relies far more on face-to-face communication and self-directing teams than any formal documentation mapping out the whole project for years in advance.

The release of products in short, iterative, cycles can mean there is little time to write the user documentation before the product is released. Also, if the product is changing with every release, there may be a need to rework the content that’s already been written.

An Agile approach to technical writing

Technical communicators who work in an Agile environment often need to adapt the way they work to meet these new challenges. In other words, they need an Agile approach to technical writing.

Agile is based on a manufacturing method called Lean, and we suggest this Agile approach to technical writing should be based on Lean principles as well.

Learning from Lean

The Lean methodology is a method for making things. Originally developed for manufacturing, today it is used in healthcare, programming and other business areas. Lean is an adaptation of the Toyota Production System, a set of principles and methods developed in Japan in the 1950s for creating high quality, reliable cars at a reasonable price.

In a nutshell, Lean’s approach is to:

Maximise the value to the customer


minimise waste.

Lean is a never ending process. You constantly seek out waste, strive for perfection, look for maximising the value. Agile shares this philosophy of continuously striving for perfection, looking to maximise the value to the customer and avoid time wasted on activities that don’t add value.

About value

In Lean, you start by understanding what the customer values in the product. Once you’re able to define value, you can then pinpoint where and how value is added during the development process.

You focus your efforts on ensuring that resources are targeted to deliver that value as effectively and efficiently as possible.

If a feature or a step in the development process doesn’t add value, it is seen as a “waste”. In Lean, you challenge whether those “wastes” in the development process are needed or if they should be eliminated.

The result is an emphasis on providing the value customers are willing to pay for, whilst simultaneously identifying where you can reduce costs.

About waste

Waste is categorised into eight types in Lean. However, we can simplify things by looking at the three original wastes that were defined in the Toyota Production System.

The three types of waste are: “non-value adding work”, “overburden” and “unevenness”. Non-value adding work can mean the waste of time and effort on activities or features that don’t give the user any value. Overburden can mean someone having more work to do than they can handle, which often leads to mistakes, defects and poor quality. Unevenness can mean the times when you have to stop or slow down, while you wait for someone else to give you a item needed in order to do the work. Instead, our goal is to have a consistent, productive rhythm to our work.

Why look at Lean instead of Agile?

Agile has developed processes and methods for reducing wastes for developers. However, these processes and methods can result in waste appearing at other points in the overall process, such when we create the end-user documentation.

For example, we might find that leaving documenting to a late stage in the development process in order to avoid the wastes caused by creating content that’s not needed or requires reworking is a false economy. This approach could be more wasteful than starting the project earlier. Using Lean can help us identify how to eliminate or minimise those wastes.

We can look at value and waste from two aspects – during production and during the use of the product by the user. This we’ll begin to do in Part two of this series.

A technical communication user’s hierarchy of needs

At the TCUK 2015 conference, Rachel Johnston mentioned the idea of a content maturity model. We thought we’d take this idea and ask:

Could we develop a model that illustrates a hierarchy of needs for users of technical communication (and in particular, User Assistance)?

A model of what?

We suggest calling this model a technical communication user’s hierarchy of needs. This is because we’re considering the different points where a user interacts with technical communication content, the information they need, and value it gives to them.

It takes a similar approach to the content maturity model Rachel suggested (shown in the photo below), with the least mature organisations providing just the legal minimum, and most mature content systems contributing to branding and evangelism.

content maturity model diagram

A user’s hierarchy of needs also enables us to compare this model to similar models from content marketing and product design. For example, the categories in our model’s hierarchy roughly correspond to Peter Morville’s “User Experience honeycomb”, as well as the key elements in product design.

Continue reading “A technical communication user’s hierarchy of needs”

Building Information Modelling (BIM) for content

Building Information Modelling (BIM) is an increasingly popular technique used in the construction industry. It involves creating XML digital models of buildings and tunnels during each stage of a project. However, these are more than just 3D animated models, as they also embed information about physical objects in the building. According to Wikipedia:

“A building owner may find evidence of a leak in his building. Rather than exploring the physical building, he may turn to the model and see that water valve is located in the suspect location. He could also have in the model the specific valve size, manufacturer, part number, and any other information ever researched in the past, pending adequate computing power. “

It means architects and engineers can “see” behind walls and discover if there are any pipes or cables that might be affected by any planned works.

This concept of an intelligent model that can be shared between stakeholders throughout the whole lifecycle is also the future for content. Organisations want the ability to know how different items of content are related, what is the structural and metadata information behind the presentation layer and how content has developed chronologically. They want the ability to use a model to plan and modify before they start the more costly work of implementation.

BIM could perhaps provide a useful analogy for Technical Authors, procedures writers, and others developing text-based content, when they are explaining the purpose and value of structured content, single sourcing and Component Content Management Systems.

Is it possible for Technical Authors to write content more quickly?

Approximately 50% of a Technical Author’s day is spent writing. However, when Technical Publications teams look for efficiencies, they tend to focus on the 50% of time spent on non-writing activities, such as researching, reviewing and planning. They assume the content itself cannot be written more quickly. To an extent, they are right, as the querty qwerty keyboard is not an optimal layout.

We’ve been going through a process of transcribing our early e-learning modules, in order to have scripts upon which we can base future course updates. As part of this project, we’ve been using a free application called Plover to help us write the content. With Plover, you have the potential to create content (in Word, RoboHelp, Flare, Oxygen XML etc) at up to 225 words per minute (wpm).

Plover is based on chorded typing. You press more than one key at a time to create words. Chorded typing isn’t new – for example, it was demonstrated in Douglas Engelbart’s famous “The mother of all demos“.

Below is a five minute lightning talk on Plover and some of the emerging hardware:

So far, in my case, I’ve been able to double my typing speed. Realistically, those of us participating in this project at Cherryleaf aim to get to 180 words per minute. The reason for this is that most people speak at 160-180 wpm. At that speed, you are able to transcribe subject matter experts in real time – which means there’s no need to record an interview and then type it up at a later date.

There is a learning curve to this method, but it is based on over 100 years of theory and practice. It is tremendous fun – a bit like learning to use a querty qwerty keyboard for the first time.

SharePoint for documentation projects

Most of the Technical Authors I have met don’t have a good thing to say about Microsoft SharePoint. In many ways, it represents how not to publish content online. It is seen as encouraging people to move print-optimised documents (Blobs) around, rather than units of content (Chunks), and users are typically left to rely on search to find which document contains the information they are looking for.

For all those issues, SharePoint may still have its place – for managing documentation projects.

Continue reading “SharePoint for documentation projects”