Divine Documentation
Dad was about my age when he said that reading the manual was better than hypothesis driven button pressing. For teenage me, that took too long. Sure, I may have crashed a computer or two but following my gut got me there. Of course my gut isn’t that smart. In the decades preceding, devices had converged on a common pattern language of buttons. Once learned, the standard grammar of action would reliably deliver me to my destination.
Image of a nebula taken by the Hubble Telescope.
In programming I was similarly aided by the shared patterns across MATLAB, Python, R, Java, Julia, and even HTML. In the end however, dad was right. Reading documentation is the way. Besides showing correct usage, manuals create a new understanding of my problems. I am able to play with tech thanks to the people that took the effort and the care to create good documentation. This is not limited to code and AI. During the startup years, great handbooks clarified accounting, fundraising, and regulations, areas foreign to me.
I love good documentation and I write documentation. Writing good documentation is hard. It is an exercise in deep empathy with my user. Reaching into the future to give them all they need is part of creating good technology. Often the future user is me and I like it when past me is nice to now me. If an expert Socratic interlocutor is like weight training, documentation is a kindly spirit ancestor parting the mist.
Maybe it’s something about being this age but now I try to impart good documentation practices to my teams. I also do not discourage pressing buttons to see what happens. Inefficient, but discovery is a fun way to spike interest.
Meanwhile, I’m reading a more basic kind of documentation. Writing English. Having resolved to write more, I’m discovering that words are buttons. Poking them gets me to where I want, but not always. Despite writerly ambitions, the basics are lacking. This became apparent recently when I picked up the book Artful Sentences by Virginia Tufte*. It’s two hundred and seventy pages of wonderful sentences dissected to show their mechanics. I was lost by page 5. The book is, temporarily, in my anti-library.
So, I’m going to the basics, Strunk and White, and William Zinsser. I’m hoping that Writing to Learn (finished) and On Writing Well (in progress) provide sufficient context about reasons to write to make the most of S&W, for the how, then somewhere down the road, savor Tufte.
* Those dastardly Tuftes are always making me learn some kind of grammar.
First 3 words you see = your team’s summer mindset.
What do you see? Tag your team and compare.
If “silos” shows up early… maybe it’s time for a better documentation strategy.
Learn how teams are using it:
Just one week to go until our webinar with the team behind the Historical Dictionary of Switzerland (HLS)!
Tue, June 11
Join RESPOND newsletter dedicated to promoting integrity, transparency, and accountability in politics.
Stay informed. Stay engaged.
