This informal post captures thoughts about three things I spend time thinking about and investigating when creating product docs:
- What the product is supposed to do
- What the product suggests you should do
- What the product allows you to do
What the product is supposed to do
This is the category of behavior associated with problems the product exists to solve. It represents the first line of questions I ask when documenting a new product. Why does this product exist? Who is it for? When should they use it?
Work in this category is tractable. The environment is littered with clues that answer the most important questions: user stories, support tickets, architectural diagrams, design specs. I can piece together a mental model and produce useful drafts without touching a piece of working software.
Is this the most important thing I spend time on? Probably. Especially for new products. People won’t use something if they don’t know what it is or how to use it. Products without users fail.
What the product suggests you should do
When I’ve answered basic questions about why the product was created, I can explore whether it really does what it sets out to do, and how effectively it does it.
For example, the product is a door. A door exists so people can enter and exit buildings. If I’m helping people understand how to use the door effectively, I’ll look at how the door is designed. Where is the doorknob? How do you activate it? Which side of the door are the hinges on? Does the door swing in or out? Is there a mechanism for locking the door? Is the door accessible via ramp, stairs, or both?
I’m not going to answer all of these questions in my documentation. Ideally, the door will answer these questions through its elegant design. If I spend time documenting obvious affordances, I’m wasting my time and disrespecting my audience.
Instead, I’m looking for places where the product’s design suggests interactions that will fail. Places where the product suggests a mental model that deviates from real-world functionality. A doorknob on the same side as the hinges. A handle that only twists up. A push bar on a door that swings in.
This stage requires that I actually use the product I’m documenting. I bring design flaws to the product team that can do something to fix them. I provide adequate communication to enable user success when design flaws won’t be fixed. I slap a “PULL” sticker on the inside of the door.
What the product allows you to do
In this stage I explore all the different things the product allows me to do that maybe it shouldn’t. The objective is to identify undefined behaviors and drive alignment on how we’re going to deal with them.
This is where tech comms finds a lot of overlap with quality assurance. This work involves a similar skill set as debugging. Personally, I think it’s the most fun.
When I discover undefined behaviors, I don’t document them, at least not right away. But I absolutely make a note of them, share them with the product team, and, if they seems like they might eventually cause problems that are a Big Deal to solve, see if we can make a plan to do something about them.
Spending time on this is often a luxury, but proactively dealing with undocumented behaviors can save a lot of money, headaches, and customer goodwill. Most successful APIs I’ve worked on have eventually had clients discover and code against undocumented behaviors in their downstream workflows. Teams with more visibility into their product’s undefined behaviors can make better judgements about the risks involved in changing systems as a product matures. At the very least, we sound a bit smarter when talking about our product to users who’ve baked our system’s undefined behaviors into their business logic.