What we mean by contextual documentation

Contextual documentation is also know as context-sensitive help. See what wikipedia says:

Context-sensitive help is a kind of online help that is obtained from a specific point in the state of the software, providing help for the situation that is associated with that state. Context-sensitive help, as opposed to general online help or online manuals, doesn’t need to be accessible for reading as a whole. Each topic is supposed to describe extensively one state, situation, or feature of the software. Context-sensitive help can be implemented using tooltips, which either provide a terse description of a GUI widget or display a complete topic from the help file. Other commonly used ways to access context-sensitive help start by clicking a button. One way uses a per widget button that displays the help immediately. Another way changes the pointer shape to a question mark, and then, after the user clicks a widget, the help appears. Context-sensitive help is most used in, but is not limited to, GUI environments.

From: https://en.wikipedia.org/wiki/Context-sensitive_help

Well this is what we’d call low level in situ documentation, describing a unique part of the GUI. It is contextual simply because it describes one or more contexts of use directly.

What should be addressed when writing contextual documentation?

We advise only providing in the first instance what the user needs to know (and doesn’t already know). That second part is the trickiest. Don’t explain an egg to a hen. So it’s what we think the user does not know or what he hasn’t thought of, typically,

  • what do i need here?
  • are there pitfalls to avoid?
  • what should i expect as a result?
  • what do i do next?

That’s a good first level. The rest depends on the complexity of the function.

If it deals with high levels of technicity, the corollary information may need to be added. The key phrase is added. You don’t have to put it all into one pile. The more the user has to read, the more probable is failure in getting the essentials across. Add corollary information to a corpus of how-to’s, faq’s, and so on. The reader will know where he is going and probably find other usefull information.

Contextual documentation is read in-situ and is in sorts a reminder for what the user may have forgotten or possibly not know. The rest is add-on, and may contribute in distracting, which creates frustration if badly managed.

What contextual documentation is not

It’s not an encyclopedia (Wikipedia is, by the way – so if you have a wiki strategy to documentation, think again). So no need to be exhaustive, just pertinent. It is not a paraphrase of the GUI – if you have to do this, then go back to the product owner or programmer and get something revised.

Who can write the first level of contextual documentation?

Well, the programmer can, if he aligns and adheres to an editorial plan, and can write decently. This may even help him see if what he has done is clear.

In particular cases, a second pass can be done by a technical writer. Technical writers are trained and experienced. It’s part of their job.

Will agile methods help?

Yes. If you push the method the whole way, contextual document (at least the first draft) can be a story. Technical writers can be part of the scrum team.