Don’t Like Writing Documentation? Then Don’t, and Learn To Be More Effective

If I broadcasted a survey to 10,000 software engineers asking how many of them love to write technical documentation, I would expect a few hundred at best to give me a firm yes. Yet, many of us would argue that this kind of effort is essential to any commercial software application of substantial size.

Therefore, that notion begs these questions:

• Is there a way to make something so essential stink less?
• Can it be made more clear and more effective for both the producer and consumer?

I have witnessed firsthand that the answer to those questions is a resounding yes. First, however, I had to nearly stop creating all written documentation before I embarked on a new journey.

Necessity is the Mother of Invention

Admittedly, I am one of those engineers who would prefer writing code over documentation. Therefore, our large Android app suffered when it came to quality and quantity of documentation because we all had the necessary "tribal knowledge" of what was going on.

That idea worked until the number of Android engineers on the project was slated to grow by about 600%. As one of the senior most developers on the project, I would often explain the same concepts or onboard new colleagues with the same ceremonies multiple times.

I knew that this effort was due to our lack of documentation. Yet, I wondered, how do you document an entire engineering process? How can I condense a 90-minute firehose introduction into a document that anyone would want to read? Then, it hit me like a ton of bricks, and it’s something that I’ve been doing all along on Microsoft Teams and Slack.

Record Your Documentation as A Video

Why hadn’t I done this earlier? I had spent hours presenting the same concepts to individual engineers and, at times, whole groups of developers. However, our brains are finite, and what ideas weren’t immediately put to use were often forgotten. I am guilty of this all of the time.

I had already mastered the art of gathering my thoughts, screen sharing them, and explaining concepts as thoroughly as necessary to an audience of one or more people. Why not find some spare time and record it once for all time? It doesn’t matter if it happens at 8 a.m. before your daily stand-up or at 5 p.m. after your workday is done.

Honestly, the only writing I needed to do was my outline of discussion points. The rest is a conversation in front of a camera or a voice-over for a screen recording.

You Already Have To Explain Your Work

Unless you work as a solo engineer on your personal project, you will need to explain your code, design decisions, and conventions. As any engineer knows, that is just a part of a typical developer process. Perhaps the easiest way to explain how something works is to tell that person conversationally; at your desk, or through Microsoft Teams. The most disciplined and challenging way would arguably be through written documentation. Then there is everything else in between. I argue that we should slide that difficulty meter as close toward the easy side as possible.

Perhaps, then, videos are the holy grail of software engineering communication. It embodies what we want to do as humans (talk) and provides visuals and a sense of connectedness.

Truthfully, how connected do you feel to the instruction manuals you receive whenever you order a some-assembly-required item, like a piece of furniture, a tool, or one of your children’s elaborate toys? How many of you would instead look up a YouTube video showing you how to do the same thing that the manual is telling you?

I see metaphorical hands go up everywhere. Why? It’s human nature.

That’s How Our Brains Work

Ever wonder why Amazon has over 10,000 results for the search term "speed reading" in the books section? Reading is not engrained in human nature. Neither is writing. According to Kam Knight, author of the revered book Speed Reading: Learn to Read a 200+ Page Book in 1 Hour, he argues that reading (or writing, by extension) isn’t a natural part of the human fabric since "reading isn’t something that originated or exists in nature."

Similarly, David Butler, author of Speed Reading with the Right Brain: Learn to Read Ideas Instead of Just Words, believes that effective reading requires leveraging both the left brain for decoding words and the right brain for efficient and effective comprehension.

Why are we going against human nature to write and consume documentation? Let’s skip the difficulty of disciplining ourselves and going against natural human intellect. Instead, let’s leverage what humans are already good at and have been doing nearly since birth: talking, pointing, showing, and using visuals.

You Already Have What It Takes

Any time I say the word "camera" or "microphone," I'm well aware of the fact that some people’s blood instantly freezes. However, unless you are in the service industry and have never used Microsoft Teams, or Slack, or Zoom, then you’ve been doing this since at least the start of COVID.

I’m talking about what is inside of you. You don’t need to use a camera; you can decide only to show what’s on your screen. Fear of microphones is dwindling, as we all use them on a near-daily basis. To explain something, act like your colleague is sitting next to you as you pick a topic to explore. (Don’t point at your screen since no one can see that.) No big audience to think about; it’s just you, your screen, and the one person at a time that will view your video.

Equipment

As far as hardware goes, most of it is free. Or as free as you already bought it gets.

• Camera and Microphone, $0: Most laptops already have these built-in. Unless you’ve been unseen and unheard at all of your company’s teleconference meetings since March 2020, then you know you have them.
• Screen/Camera Recording Software, Option 1, $0: One option is to use OBS Studio. It is a free, open-source application for broadcasting and recording microphones, cameras, and screens. It takes a bit of getting used to, but it’s certainly a solid choice.
• Screen/Camera Recording Software, Option 2, TechSmith® Camtasia®, $250: Camtasia Studio is pretty much the best choice in the industry. It has a full editing suite to help you correct mistakes, adjust audio, and make the producer/consumer experience as simple as possible. Too expensive? Ask your company to get behind the initiative with a business license. They will probably make that money back in a snap because they aren’t paying you to labor under mountains of written documentation anymore.

Hosting

Once you have your videos, here are a few places to put them:

• Microsoft Stream: Think of it as YouTube for your company. If you’ve ever uploaded to or watched a video on YouTube before (i.e., everyone on the planet), then this will feel very similar. It also includes apps for iOS and Android.
• Atlassian Confluence: Does this product even need an introduction? Even though it thrives at processing written documentation, it’ll handle your videos brilliantly. Then, you can use the sidebar to organize your collection as you please.
• TechSmith® Screencast.com®: It goes together like peanut butter and jelly with Camtasia Studio.
• File shares, Microsoft OneDrive, Google Drive: No one needs a fancy application to view your documentation. If it’s informative, your colleagues will consume it no matter where it is hosted.

Written Documentation Has a Small Place

Engineering diagrams, tables of information, and REST contracts are items that I would argue still need to be written down. If I could wave a wand to make all of the grunge work of documentation disappear, I would.

In reality, there is still a place for it. However, that place is much smaller than we often perceive, and we can explain much of it away. Literally. In video format. In doing so, we attach to a much more natural part of our brains as we explain concepts that flow much more simply to our audience. With all of that effort spent more effectively, you can get back to writing your software. Your team will thank you. And your company probably will, too.