What we mean by contextual documentation
Contextual documentation is also know as context-sensitive help. See what wikipedia says:
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.