The Secret to Documentation
I learned something about documentation this week.
When I think of documentation, I also think of templates. In fact, I have my own template for writing up technical documentation (please feel free to take it, use it, riff on it, whatever - just document!).
But templates...they can get stale. They can be confining. They are often boring.
My clique and I looooove good documentation wherever we find it (help text, lines of code, embedded videos, walk-throughs, step-by-steps, etc). I know some of the best documenters out there. And what I learned this week is what makes their documentation so good. It isn't the level of detail in the technical parts. It isn't the branding or the colors. It isn't the platform they are using or even the format they stick to.
It is the fact that I can hear their voices in their documentation. It is like a conversation I'm having with a friend.
You might think that making documentation as "evergreen" as possible and keeping it in a non-descript voice that can't be traced back to a single author would be the best way to create documentation. Shouldn't that withstand the test of time and staff turnover? But I've been bored to tears with a lot of those resources and don't actually use them at any point. No one wants to re-invent the wheel, but when it is either fall asleep from writing the documentation or re-invent something, then I’m about to make a really unique wheel.
I'd like to share two examples of documentation where I tried to keep it real and not fall into the template-trap that could have left these documents feeling super dry and dull.
First, I was helping a great nonprofit using Canvas (a popular Learning Management System) to get their data out of the system using APIs. Everyone is using APIs somehow in their work right now - even if it is just some connection between Google products. Application Programming Interface is the fancy technical way of talking about how two systems can "talk" to each other, and how we as humans can "talk" to our systems. APIs are the way that Google products talk to each other (like conversations between your Gmail and your Google Calendar). They are NOT the easiest concept to understand. So in my documentation, before I could really tell folks at this nonprofit how to use the API calls that I built for them, I had to make sure we were on the same page about APIs in general. I started my documentation with my own summary of APIs - what they are, how they are used, and why we are using them. I am particularly proud to say that I have left this organization with a document that uses the term "gobbledy-gook". You can read the shortened version of this documentation here.
Second, I am helping an organization I've been with a long time to clean-up the many many reports, report folders, and report types in our instance of Salesforce (so common for so many orgs). To present my project plan and documentation around this work, I started typing up the standard kind of documentation - mainly just an outline of what we would do to "streamline" our reporting in Salesforce so data is easier to access for staff members. But to be honest, I was dragging my feet on it because the documenting of it was fairly boring (yes, even to someone like me who lurves Salesforce reports and digital organization). So I took a step back and just started playing around with some of the information and the formatting, and before I knew it I had a piece of documention unlike one I had ever made before - a creative one. You can see the redacted version here.
The reactions to these two documents were some of the best reactions I've ever had for any piece of documentation I've made before. And I personally had the most FUN putting this documentation together.
One of the most important things that these creative formats and conversational-tone documents helped me with is the challenge I feel knowing that any and all technical documentation can go stale and need updating almost as immediately as you share it with others. Now ain’t that a b*tch? I mean, why write something like this down if you are just going to have to keep reviewing it, updating it, changing it ALL THE TIME?
I don’t have a good answer to that one - it’s part of the work. It feels a bit intimidating and overwhelming to me, but so did system and software updates before I embraced change in those areas. Being creative with the documentation helped me somewhat with these feelings. But, like all things, I’m a work in progress there.
