06 May 2025, 16:31 (IST)

I often hear advice about writing documentation that assumes an ideal reader. The kind of reader who when they see an estimated reading time of 45 minutes, cancels their dinner plans, makes a large pot of coffee and commits to an intense period of concentration.

It’s reasonable to expect when writing a novel, that the interested reader will try to devote sustained focus to the book. If they like it enough, they might read it all at once, even if it takes several hours. We are certainly not expected to account for the reader who likes to glance between two or more books at the same time, or who actively dislikes books and only reads them out of professional necessity.

Yet that expectation is not necessarily reasonable when applied to software documentation, where the reader is – at a minimum – context-switching between the documentation website and the software being documented. If your documentation links to external documentation, they may be even be switching between documentation sets.

Something as mundane as being able to find where you were before you glanced away from the documentation and towards your second monitor becomes far more important in these non-ideal circumstances.

For example, it may be easier to return to step 7 than the seventh unnumbered bullet or the sentence about that last action you tried… wherever it is.