Share via


Context in Topics

The documentation team I'm on is starting to write topics for a new product. It's a fairly small documentation set as far as topics that explain how to do things—around 50 topics. (I'm not counting API reference topics, of which there will be hundreds. I don't want to talk about that right now…) One of the things I'm thinking about while I'm editing is making sure that each topic provides a context for the reader. I want it to be obvious to readers when they come to a topic where in the process of using the product they are; they should know if there are prerequisites to using the information in the topic, and they should easily see what the next step in the process is.
That sounds like an obvious goal, but it's hard to achieve with larger documentation sets for products that have many uses. Often the information can be used different ways depending on what you want to do with it, so there isn't a good way to provide context for every situation. Trying to contextualize even the most common uses could make the topic difficult to read. The information is just there, isolated, and it's up to the reader to figure out what to do with it. I've been in that situation as a user before, and it can be pretty frustrating.