Technical Writing Guide: Emphasizing Personal Experiences with Callouts
Draw attention to your personal experience without disrupting the flow of your narrative
Congratulations 🎉
If you’re reading this, you probably want to improve your technical writing skills.
Background:
I’m a Data Engineer with 6+ years experience. I’m also an editor for Data Engineering Things publication.
I review a lot of technical articles and thought I’d share some techniques to improve technical writing.
Goal: Include Personal Experience in Technical Discussion
You are writing an article about how to do XYZ and want to include a time where you needed to do this in your career. How do you do it?
Bad way:
Include continuously in your narrative.
Good way:
Break narrative, switch context, then switch back.
Best way:
Exclude from narrative, include as a callout.
Examples:
This can be a lot to imagine. Let me show you with some examples.
💡 For each of these examples, I will be describing ProtoLint, a sophisticated protobuf linter. I purposefully want a complex topic to demonstrate the challenge associated with context switching.
Ex: Continuous Narrative ❌
ProtoLint’s enum rules, such as ENUM_FIELD_NAMES_ZERO_VALUE_END_WITH are necessary when compiling to C/C++ bindings because of the namespace associated with global paths. A server started failing in my previous role and I didn’t know why and after hunting down the bug, I found it was because of a namespace collision with a protobuf enum. Now, I use the rule to avoid this problem.
This is bad! It is difficult to distinguish the technical guidance from the anecdotal experience.
Ex: Context Switch ✔️
Implementing ProtoLint as part of your pre-commit/CI workflow is easy — add their pre-commit hook and you’re done. Do note that protolint is written in go (the hook will need go installed to execute). Make sure your CI container has go already installed (or add as a dependency).
It’s important to mention go as a dependency, since, if you will want to write any custom rules for protolint, you will need to do so in go. I was working on a team which specifically wanted to avoid implementing any go code, so we ended up ruling out protolint as a linter option. Keep this in mind as you research possible tools~
This is better! It’s clear which aspects are instructional. The personal experience, while relevant, is separated from the technical guide.
Ex: Callout 🚀
Rule enforcement can be configured on project and directory level through the .protolint.yaml configuration file. Rules can also be ignored on the file level, or inline level.
💡 If you’re implementing protolint in an existing (and mature) repository, I highly recommend enforcing strict rules on the project level, then exclude all existing files which violate these rules.
💡 This allows you to implement your linter separately from migrating your existing code. Migrating existing protobufs to be compliant with new rules can be done bite sized — smaller PRs and higher velocity. As you do, remove them from exclusion.
End of example. ☝
This is best! The instructional aspects are completely separate from the reflective / commentary. This allows for distinction of a technical tone from a highly personal one, with minimal context switching.
Good Examples:
Here are some technical articles which effectively insert personal narratives:
What I Learned from Surviving a Coaching Plan in Silicon Valley
Xinran is a master writer who shifts her narrative so rapidly and effectively, you’ll feel like you’re reading a script to a movie. Specifically, her use of media as context switches are clever and effective.
The 4 Types of Technical Interviews for Data Engineers
Jeff does an amazing job at inserting his reflections and humor through callouts.
Ingestion of data is over. But not as you know it
Hugo has a brilliant narrative and effectively shifts his narrative to include his insights. His introduction is also a bit of a callout, which I really like.
Conclusion
Balancing a technical narrative with personal commentary or insight is a challenge. It’s important to include your voice (that’s what people want), without detriment to technical discourse.
The best way to do this is to use callouts. It’s acceptable however, to context switch, though this may make your article slightly more difficult to navigate.
Technical Writing Guide Series:
This article is part of a series on technical writing best practices.
- Adding Links
TLDR: If something is important, link it! - Technical Writing Guide: Compelling Titles and Subtitles
Draw people in with a well crafted title. Focus their attention with a good subtitle.
