Cleaning up my kitchen after the hurricane of toddlers left for daycare, and thinking about how daily housework is similar to writing good documentation. Let me explain.
A well-maintained house isn’t defined by how clean it is or organized it is. People only notice things when they’re missing, in the wrong place, or are dirty.
No one notices the 3 extra rolls of toilet paper that is available when you weren’t paying attention and you have that 1 slice of TP left on the roll. Or the constantly stocked pantry or medication cabinet. Or the extra jugs of milk on standby, or the frozen pizza in the freezer “just in case.” No one notices that there are always extra diapers and wipes available, and a clean floor.
What they notice is the sand on the floor under your feet. When that one supplement is missing. When you are stuck on the toilet with no TP, experiencing existential dread. When you can no longer push out that last tiny dollop of toothpaste. When you can’t find your keys, license, and phone in the “usual place.” When the laundry isn’t done and you can’t find that one specific item you need for their daycare tomorrow.
People notice when your day’s expected “flow” is broken.
I spend countless hours every week making sure everything is stocked, ready, cleaned, washed, and organized. But there’s really not much to “show” for all that work, because when it’s running smoothly, it’s “invisible.” Only when there is a flaw, does the invisible labor become visible, and at that point, it’s to the detriment of me, the house manager.
Documentation is similar. Most people don’t read documentation and go, “Damn, that was a really good tech doc! Let me rave about it to my friends/LinkedIn!” Most people read it, and if it’s good, it solves their problem. They pat themselves on their backs and move along. It aligns with the flow of their process, and it helps them feel good, and helps them accomplish their goals.
But people DO notice when it’s BAD documentation. When something doesn’t make sense, seems way too AI-y, is missing steps, or is poorly written. Too long or too short, too many graphics or not enough. If it’s in video format, you’re inclined to click “x” in the first 30 seconds and go look for another video.
When I create courses or documentation, my goal is to make it as friction-less as possible. Any area that could create question marks, I define. I mange the scope so that I am not going into too much detail that the audience doesn’t require (even if I end up simplifying concepts a bit). I try to use language and metaphors that are comprehensible to my audience base.
I look for other documentations and resources that are created with the audience in mind, and link them. I provide links to more in-depth documentation for people who are more advanced and want more granular documentation. I try to create content in different mediums for different learners (videos, books, blog posts, etc.).
I try to meet the audience where they are at, and run alongside them to keep pace with their flow. And hopefully, it means that I help them answer their questions or do what they set out to do.
Unrelated, but I just saw a House Manager role in DC for $150k + health insurance.
My most recent technical documentations/tutorials are available at awsnewbies.com! And the rumor is that my LinkedIn Learning courses are now available in Polish and Italian!