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 training course – Writing skills for developers

Today, we’ve released our latest training course – Writing skills for developers. The course teaches developers the key skills of technical writing for software user documentation.

writing techniques web page

Although it would be better for a professional technical communicator to write the end user documentation, for some organisations, this isn’t always possible.

It is for developers who:

  • Need a solid understanding of the fundamentals of technical writing
  • Want to communicate more clearly and effectively
  • What to know how little, or how much, they should write
  • Want people to answer their own Support questions

The course comprises 14 modules in total, which delegates can complete at your own pace. The course modules are delivered over the Web in small, manageable video presentations. The course handouts and exercises are downloadable as Word or PDF files.

We can also deliver this course as a classroom course for development teams.

For more information, see: Writing skills for developers training course.

What is the minimal amount of user documentation you should write?

In researching what developers wanted to learn about writing documentation for users, the most common issue related to how much, or how little, they should write. One developer said:

“I would want to know what is the minimum I should write. If you can persuade me what is the necessity of each thing I’m capturing, and the voice I should use to make it most acceptable, I think I’d tune in.”

We’ll look at this question in the Writing Skills for Developers course, which we will be releasing soon. In general, you need to:

  1. Meet the legal requirements (which differ depending on the product, and the country).
  2. Provide enough information so that users don’t give up using your product, if they get stuck. For example, how to install the software, and how to get started.
  3. Consider the support calls, and whether you could avoid any of those by having good user documentation.

That might appear a bit too vague, so let me go back to one of the sentences above:

“If you can persuade me what is the necessity of each thing I’m capturing”

Before you start writing, you should define the purpose and audience for each deliverable you create. There should be a use case:

  • Without documentation, is it clear what the user should be doing? is it clear what the user should be doing first?
  • Is it clear how they should be doing the task?
  • When they have to choose between options, do they have enough information to make the right decision?
  • When they have completed a task, do they know what to do next?
  • Are there any concepts or terms the user might not understand?

You can assess what topics to cover by doing some basic usability analysis. However, if you think about the tasks, the process (workflow), and any unfamiliar concepts, you will be on the right track.

Getting users to read the Help rather than call support

We spotted an interesting statement by the “Father of Behaviour Design”, BJ Fogg:

“For somebody to do something – whether it’s buying a car, checking an email, or doing 20 press-ups – three things must happen at once.

The person must want to do it, they must be able to, and they must be prompted to do it.

A trigger – the prompt for the action – is effective only when the person is highly motivated, or the task is very easy. If the task is hard, people end up frustrated; if they’re not motivated, they get annoyed.”

See Ian Leslie’s article “The scientists who make apps addictive“.

If we want users to read Help text instead of calling the support line, then we maybe we need to meet those three criteria.

We can assume the user is motivated to fix their problem.

We can write instructions that are clear enough to make them able to solve the problem.

Where some applications fall down is they don’t prompt the user to read the online Help. The link to the Help text is often tucked away in the right hand corner of the screen.

Instead, we could put some of the Help text into the User Interface or the dialog screens,  and we could prompt the user to follow a link to more information. Doing this could get users to read the online Help rather than call support.

Which type of platform is best for developer documentation?

At the Write The Docs event in London last night, Gergely Imreh presented Resin.io’s approach to customer-driven docs – documentation as self service support. Resin.io is a software company that provides Linux containers to the Internet of Things. It sees itself as a support-driven organisation, and so documentation is very important to them.

The discussions at the end of the talk were around which type of platform is best for developer documentation.

Resin.io uses an in-house system, based on Markdown and a flat-file publishing tool. They build pages from “partials” (snippets of re-usable chunks of information) to create “parametric information”. Pages can be built to match different criteria. For example, using Resin.io on a Raspberry Pi and Node.js. It provides an authoring environment that is easy for developers to use; it doesn’t require a database-driven CMS; and the content can be treated in a similar way to the code. The challenge with this type of system is getting it to scale. The “intelligence” of the system is through storing content in folders and using scripts within pages. As the grows, they are finding it harder to manage.

Gergely said he’d like see if a wiki-based system would work better. Content would be easier to edit, as pages would be more self-contained.

Kristof van Tomme suggested using a database-driven CMS. Pages would be built “on the fly”, by the CMS. In this situation, the “intelligence” of the system is through metadata wrapped around each topic and the database software that’s managing the content. The downside is it can mean there might be challenges in moving it to another platform at some stage in the future. You also have to manage the database and protect the CMS  from potential hacking.

Another suggestion was to use a semantic language to write the content. This could be AsciiDoc or DITA. In this situation, the “intelligence” is placed in the topics and with the writers: they “markup” sentences or paragraphs for each applicable parameter, such as audience and computer. These can be published as flat files or be managed by a database. This approach is scalable and tools-independent, but it requires much more work by the writers.

What’s best depends partly on your view of the problem. Is it a information design problem, a software problem, or a data management problem? There are pros and cons to each approach.

Is documentation a dirty word?

Daryl Colquhoun has written an article in tcWorld about the international standard ISO/IEC/IEEE 26512. He explained the standard is going to be revised and renamed: from “Systems and software engineering – Requirements for managers of user documentation” to “Systems and software engineering – Requirements for managers of information for users”.

The reason for this, he states, is because, in many parts of the world, the term “documentation” is associated with a printed manual only. The neutral term “information for users” refers to all types of content: Online help, audio, video, and Augmented Reality.

The problem with “information” is it can mean many things. Information for users could mean the weather forecast. We may well need to move away from the word documentation, but I’m not sure we’ve yet come up with a suitable alternative.


GDS publishes its new design for technical documentation

The Government Digital Service has been working on establishing a standard design for its technical (i.e. developer) documentation. This content is for systems architects, developers and users of the GOV.UK platforms and APIs.

You can see an example at: GOV.UK Platform as a Service

Gov.uk technical documentation

Cherryleaf was given a preview of the new design a few months ago, when we ran an API documentation training course at GDS. We made a couple of suggestions, which look like they’ve been included in the final design.

The documentation has these main sections:

  1. Overview. This includes why you would use it, and the pricing plan.
  2. Getting started. This includes prerequisites and limitations.
  3. How to deploy
  4. Troubleshooting
  5. Managing apps
  6. Managing people

Elsewhere on the website is information relating to support, the product features, and the product roadmap.

As with other GOV.UK content, the team carried out research into what developers wanted, and they carried out usability testing. I understand the researchers discovered developers preferred content to be on a long, single page, and that they would be working in a two screen environment. Using long pages enables users to search and navigate with the keyboard, rather than the mouse. GDS also looked at other developer websites, such as WorldPay and Stripe, for best practice.

GDS is highly regarded in the technical communications community for its excellent work on the GOV.UK website. This means it is likely other organisations will copy GDS’s design for their own developer documentation.