Matt Webb wrote a post about organizing data and mapping the experience of the web, and that made me consider how the decisions about documentation structure, especially in the early stages, require similar decisions.
Technical documentation functions as a map for your product. For specific users, your documentation provides wayfinding guidance and provides the information necessary to navigate the space relevant to your product.
Beyond a map for your product, technical documentation can also map out specific workflows within your product—specific routes, one might say.
For example, diagramming and describing how data flows through the 55+ different systems that comprise Facebook. Without that documentation, you might find yourself in the same situation as some Meta engineers did in March1, admitting that:
“we have a somewhat strange engineering culture compared to most where we don’t generate a lot of artifacts during the engineering process. Effectively the code is its own design document often.” If the code serves as the documentation, that’s the same as having street signs or individual transit stations, but no sense of where you are within a larger system. You need a map to add a layer of intelligibility to the individual parts of an overall system.
Considering your documentation as a map can help you when you’re struggling to know where to start when writing minimum viable documentation.
What kind of map might you draw on a napkin about your product, or about a specific data interaction or user interaction?
- What is the key wayfinding information? What are the intersections or landmarks to be aware of?
- What would confuse someone if you left it out of the map? Are your steps complete enough to help someone get to their desired destination?
- Do you understand the destination and the person you’re guiding well enough to draw such a map?
If you consider those questions the next time you need to write documentation about a product, a data flow, or a user flow, you and your customers will be much better situated.
As disclosed in a court filing reported by The Intercept in Facebook Engineers: We Have No Idea Where We Keep All Your Personal Data and further reported on by Vice in Facebook Engineers Admit They Don’t Know What They Do With Your Data. ↩︎