Code Is Poetry, but GIFs Are Divine: Writing Effective Technical Instruction

I was slated to be the second-stringer for a big client project. The lead had held posts at prestigious outfits like Boston Consulting and Pricewaterhouse and had an impressive retinue of technical skills. However, this person had never before developed any technical content.

We’ve likely all worked with someone who is a master technician but unskilled at communicating their knowledge. It takes a supplemental set of skills to communicate about technical information, and it’s something the true domain experts often don’t possess because they’re busy going deeper into their thoughts. On the other hand, I had spent years blogging and keeping an active voice in the analytics community. 

Each of us is wired differently — the lead on the above project quickly left to go back to “regular” data analyst work, and I stuck around to complete the project, to the surprise and delight of both me and the client. While I love going deep on data analysis projects, I’ve found my talents are often better suited to getting others started with data analysis themselves. 

Over time, I’ve had the fortune to work with many of the biggest names in technical education to develop data analytics curriculum. Through this, I’ve learned just as much about data analytics as I have how to present about data analytics. 

Below are some concrete steps on building effective technical content. Caveat: While I developed this post with written data analytics content in mind, I believe that someone developing, say, a video course in web development could also benefit.

This is not a systematic guide to developing effective technical communication, but rather a laundry list of pointers. If you have others to share, please leave them in the comments.  

Hook the reader

“Buy the hook and you’ll buy the story.”

The “hook” is a literary device to reel readers into a story early. Without a good hook, readers are unlikely to buy into the story: they have not become “emotionally invested.” 

Technical communication also needs a “hook:” ideally, this is some real-life scenario that you have described that the reader can imagine actually encountering in their job. However, reproducing a real-life work scenario to a T is often difficult, due to the complexity and proprietary barriers of the workplace.  

When I started writing about data analytics, I wanted all of my examples and demonstrations to be directly about business. Otherwise, I assumed my audience’s reaction would be something like: “This is about flower measurements. What does it have to do with working at a bank?” Over time, I learned that it’s hard to find real, comprehensive datasets about business.

An audience comes to you to learn something new, not for you to simulate their current workplace environment. Students can be just as involved in learning about statistics from a dataset about snails as they would about the results of a retail A/B test. The important part is to “hook” the students into the data. I do it by telling a story about a scenario under which it’s a useful analysis. 

To paraphrase Tolstoy, all real-life datasets have similar problems: they’re always “non-standard” in a way that’s very hard to replicate from doctored data. That’s why I attempt to use real-life data whenever possible. This can take a while to find the right data, but it makes the lesson come to life.

Imagine what would make your understanding of technical subjects “pop” more: analyzing spoofed data that lacks the ambiguity of the real world, or replicating the results of a research study using an original, real-life dataset? Now that’s a hook. 

Relate unfamiliar information to familiar information

Another way to get users invested into what you’re teaching is by relating new information to things they already know. When teaching subjects like SQL or R, I like to relate foundational concepts to familiar tasks done in Excel. A learner is more likely to understand the “so what’s” of advanced data analytics features if, again, they have “bought the hook” of what R or SQL is really capable of. 

There’s a tendency, especially in data science, to dismiss Excel as not a “serious” data tool. The charges are usually as follows: can’t handle big data, prone to error, not reproducible. These points all have some truth, but none of them negate that Excel is a powerful pedagogical tool for learning about data analytics. 

Sorting and filtering, aggregating, combining data sources, constructing well-designed tables… these are all common tasks faced by advanced machine learning engineers and junior Excel analysts alike. There’s no need to explain why these tasks are important: Excel users live in this stuff! By contextualizing and relating unfamiliar information to familiar, learners are able to pool their knowledge across multiple tools to a greater understanding of how to work with data. 

Employ the IKEA effect

“Never tell people how to do things. Tell them what to do and they will surprise you with their ingenuity.”  –George S. Patton

Research from behavioral economics has indicated that consumers place a disproportionately high value on products they have partially created. This so-called “IKEA effect” can be used to great effect in teaching technical subjects.

When I first started writing about data analytics, I thought that including things like drills and challenges were unnecessary, because nobody would actually do them. This isn’t true — there is a real demand for learning exercises and not just straight “how-to” tutorials. 

But drills and “paint-by-number” tutorials are one thing: learners may claim to want to be told exactly how to do things, but with some open-endedness they will surprise themselves, and you. As a mentor at a coding bootcamp, students have constantly surprised me with their innovative approaches to open-ended projects. We educators often have one way to do things in mind, and students go in a completely different direction, while still fitting the description of the project. 

Learners want to personalize the content, and create something of their own. Let them, with open-ended tasks and challenges. 

Don’t reinvent the practice of computing…

By this, I mean your goal shouldn’t be to receive a Turing Award each time you write something technical. 

The deeper I’ve gotten into data analytics, the longer my YouTube videos have become. I could easily take an hour to record a tutorial, but this is not a great way to communicate. I could take a year to write the magnum opus on some technical subject, but then I wouldn’t know how my audience would respond to this topic for a year, and even then, the resulting asset is hard to absorb.

Not every blog post has to be the “ultimate guide” to a topic. Not every learning guide has to list every conceivable way to do something. Focus on the “pain point” you’re addressing for your audience, and how to solve it most efficiently. Sometimes, even the most efficient solution is still pretty labyrinthine. If that’s the case, don’t be afraid to break the content into discrete videos or blog posts.

Lastly, if you’re starting a blog about a technical subject, remember that the “niches are in the riches.” Chances are, you are never going to write everything about Excel, but you can build the definitive resource for retrieving weather data in Excel, or performing dimensionality reduction in Excel. 

… but do rehash it.

By this I mean to make sure that users have all the resources at their disposal to fully step through your example. For example, if you are writing about Power Query, include a link to the download page. If other assets are needed, state them clearly. 

Data scientists call a project “reproducible” when an outsider can fully step through and conduct the project themselves and return the same results. Your blog post should also be reproducible. Give your audience the context of what knowledge or technology is prerequisite, and where they can go about learning it. Here’s your chance to link to outside materials or a paid “starter pack” course written by you. 

Remember white space

People read from screens about 25 percent slower than they do from paper. It’s tough work! All the more so when your content is technical, and each step must be followed to lead to the outcome.

When in doubt, add white space.

Short paragraphs allow the eyes to relax, and helps the reader track their progress. Paragraph headers, quotations and other images break the content’s monotony.

A GUI means GIFs

Of all the praise I received for building data analytics content, perhaps the most frequent is my use of GIFs. 

Some data analytics tools, like Excel and Tableau, are primarily GUI-driven (That’s graphical user interface.). It can be awkward to explain all the steps taken to navigate a “point-and-click” maneuver. It’s often easier to show than tell how to work a GUI. But, how can you bring written content to life like this?

I do it with GIFs.

Above is a GIF I made to illustrate how to hide the contents of a cell in Excel. Following the steps:  “Place your cursor in cell A19, hit Ctrl + 1 on your keyboard,” etc.,  can get tedious and confusing. Placing a static image of the Format Cells menu doesn’t really show the user how to actually get there. 

Why not throw in a quick five-second video illustrating the concept for eternity? That way, the demonstration comes to life. 

If you are interested in developing technical content, invest in a Camtasia license, now. It is expensive. I tried to save a few by using an inferior alternative, but ended up just paying for Camtasia anyway.

Camtasia has a feature to export a production as a GIF file, which is how I produce these crowd favorites. 

Explain discursively and through demonstration 

In the above example, it seems silly to write down each step if it’s just going to be explained later in a GIF. Without it, the content becomes disjointed. Why have writing at all, if a series of GIFs will do? And why make the GIFs, if it’s been explained already? 

Each medium should build on the other — a good technical curriculum will expand on the demo assets with writing, and vice versa. 

Comments are divine, too

The above rule means that, for code-based content, be sure to include ample comments within the code itself, while also explaining it in the discourse. Users will often paste this code and implement it into their own work, so you want it to be as “shovel-ready” as possible when used out of the context of your post. 

Make sure that users can easily repurpose the code for themselves too. But this will be good for you as well. 

Always be repurposing

This one is for you and not the audience, but stretch any ideas you have as thin as you can. I always make a YouTube equivalent to any technical post I write. I often use the same datasets repeatedly. I also develop a series of expressions and vernacular that become a part of my style. You’ll hear me refer to VLOOKUP() and PivotTables as the “duct tape” and “WD-40” of Excel, respectively. You’ll hear me call R packages “aftermarket parts” that get added to the base.

Conclusion: technician, meet designer

What prevents the genius technician from teaching and communicating effectively? It’s understanding the user’s needs, and building something to fulfill them. Put simply: it’s design. Data scientists, developers and other technical professionals would do well to learn about design. After all, the technician who can up-skill a data team stands to gain when continuous training must be at the core of every competitive organization. 

But as I said earlier, we are all wired differently. Many teams and organizations rightly prefer to focus on the tactics, and have outside talent design their training. 

If you could use a hand in bringing technical upskilling to your organization, don’t hesitate to get in touch. I also welcome you to sign up below for my newsletter. In return, you’ll get free access to my exclusive data education resource library.