Technical Communication
Or: 6 Principles for a Winning Technical Talk or Blog Post.
And Also: Why Should You?
1. Why am I Here?
It was the evening train ride home. I was haunted by a question that kept bothering me: “Why am I putting so much effort into my many tech-related extracurricular activities?”.
I decided to take my mind off this existential crisis, and instead dedicate the time to learn a new tool that would assist me in my job. Half an hour later, I was angry at the useless and condescending internet, where all the resources I could find assumed I already knew what I actually came to learn.
Determined to not let the internet beat me — I pledged to learn how to use this tool, against all odds, and I would even make a tutorial for it!
And then I realized - this is why I do the things I do 💡!
When I am frustrated with the world, my method for dealing with the rising anger is to do something about it!
So, although I didn’t learn how to use this tool during that train ride, at least I solved my existential crisis...
And why am I telling you all this?
Because I have a short fuse.
And in the past couple of years I have gotten angry a lot 😡.
So I wrote many blog posts, gave many technical talks, and dealt a lot with Technical Communication - how could I improve? and why bother?.
In this post I will share from my experience trying to answer these big questions.
Oh, and I also shared my story to illustrate the power of opening with a story .
2. Why are YOU Here?
You, the reader, are probably here because you are actively looking to get better at something. This is what Medium is mostly about, right?
Hence I allow myself to assume you acknowledge the value of continuously learning, constantly evolving and keeping up with professional developments.
3. Why are WE Here?
We, you and I, are here to improve our Technical Communication skills, that will in turn serve us in promoting our ideas, our projects, ourselves.
Perfecting our Technical Communication skills is a process with a positive feedback loop:
- By becoming better communicators of our professional knowledge, we:
- Learn to be better professionals ourselves, thus we:
- Open up new opportunities to share our knowledge, and so we:
- Become better communicators…!
4. The Cocktails Model
We were taught that every good story has a beginning, a middle, and an end.
But which part is which? How long should each part be?.
I format my stories using cocktail glasses, which inspire different structures for different circumstances. So when I am planning a talk or a blog post, I ask: “which cocktail is best served with my content today?”.
Layered Cocktail - “Someone Who Knows”
This post is structured as a Layered Cocktail, which I believe is ideal for an advice post. I divided the advice in this post to separate sections, such that each section contains a clear, standalone message. When read together, these advice make up a story, and separately they each have individual value.
The Snifter - “I-am-not-exactly-at-the-right-place”
It was about a year ago. I was invited to speak at a major programmers’ conference, to present an algorithm I developed. I soon realized that although in the heart of this algorithm are some deep mathematical concepts, they were not aligned with the heart of this programmers’ conference. I concluded that in order for the audience to get the most out of my talk, I should use the Snifter structure.
I started with the backstory that gave the motivation to the project, supplied context into why this is a problem worth solving, and illustrated why it is a hard one to solve. I spent only several minutes laying out the details of the algorithm, and concluded my talk with a message that speaks to all audiences.
This talk turned out to be a great success - it introduced me as a professional in front of hundreds of peers, which encouraged many of them to both seek out my advice and share their own stories for me to learn from.
Furthermore, I got a surprise I wasn’t expecting.
Several months later, when I was looking for a job, I talked about this project in job interviews. Since I was well rehearsed, it was easy for me to talk about it in a clear and structured manner, in a way that emphasized my skills.
Which brings me to the last type of glass I want to share with you today.
The Margarita Glass - “So, What Do You Do?”
This conversation can happen in your living room, at a coffee break in a conference, or as it happens so often, in a job interview. Whatever the circumstances, the principles are the same.
You should start with the widest lens you can think of. Short description, 2–3 sentences, that both kids and parents can understand. Then, gradually go deeper, adjusting your explanations to your listener’s background and attention span.
5. To Sum Up
Every talk or blog post should end with a concluding statement, sending the crowd home with the main message fresh in their minds.
Moreover, in a written blog post, a concise and reliable tl;dr will frequently convert a browser to a reader.
Tl;dr
- Why am I here? - What is my motivation? What is my personal story?
- Why are YOU here? - Know your audience. What is their background? What is their motivation?
- Why are WE here? - What is the purpose of this? What are the takeaways?
- The Cocktails Model - choose a structure for your content that serves your 3 Whys.
- Tl;dr.
6. The End.
To grab your audience’s attention all the way through your meaningful content, you should finish on time.
So this is me finishing my 1000 words.
