The adult swim cartoon Rick and Morty has a running gag about a tool called a plumbus. I’ll spare you a full 360 image of the plumbus, as the other side of the widget looks a little… weirdly NSFW. While traveling to other dimensions and galaxies, it’s advertised on tv commercials as a common, necessary object–so well known, in fact, that there’s no reason to explain it.
All comedy aside, the plumbus anecdote is an excellent cautionary example for documentation. This thing in our codebase? That internal software tool we’ve been using for half a decade? Everyone knows what it is. Why explain it?
New hires can be great additions to a team without having 100% of the experience necessary to do their work. Maybe they’re coming from another industry and need a bit of a primer on your specific niche. The gap can also be generational. I once sat in on a career day for a high school group where one of the presenters used the term zip drive to describe storage, and watched every Gen Z teen in the room blink in confusion.
To craft good, friendly documentation that will work for readers of any background or experience level, you want to ask yourself the following questions.
Who Will Be Reading the Docs? 📖
Developers will have an understanding of coding principles. Sales folks, support teams, and account managers may not. Identify who the reader with the largest gap in understanding will be, and build the docs up from there.
Can I Borrow From What Already Exists? 🤝
That said, you don’t always have to draft everything from scratch. Let’s say you’re making an internal user guide for Slack. In a software company, most employees will have already used the tool at previous jobs. Recent grads or industry transplants may be experiencing the tool for the first time. Slack has its own excellent documentation. Try linking out to those docs, either in one section for total beginners or interspersed throughout your guide as terms are used for the first time. This allows newbies to follow along without giving paragraphs of overly simple information for your more experienced employees.
Have I Established a Timeline? 📅
When explaining a product feature or concept, remember to include a high level history to allow those who join the company after critical events to keep up with the pack. This is crucial for the success of high-growth companies. Which of these statements is more illustrative for any tenure of employee?
Auto lock is no longer something we offer.
Or,
The auto-lock feature was sunset in 2021, but remains for 5% of customers who can’t function without it. We plan to extend this feature for another two years. Account managers have the most current information as to which customers fall into this bucket.
(Hint, it’s the second one.)
Can an Image or Video Make This Better? 🖼️
Visual depictions are no replacement for text explanations, especially in terms of knowledge base and wiki searches that pull from text to return related results. But sometimes, text alone can’t properly explain how to complete a task, or how something works. A well placed screenshot or video snippet can make a world of difference for new and upskilling employees.
Now, back to plumbuses. Did you know that they’re worth six and a half brapples?