here are my top tips on technical writing after 8 years and 700 posts

You can become a serverless blackbelt. Enrol to my 4-week online workshop Production-Ready Serverless and gain hands-on experience building something from scratch using serverless technologies. At the end of the workshop, you should have a broader view of the challenges you will face as your serverless architecture matures and expands. You should also have a firm grasp on when serverless is a good fit for your system as well as common pitfalls you need to avoid. Sign up now and get 15% discount with the code yanprs15!

Since Dec 26th 2009, I have written regularly on this blog on a variety of technical topics. Suffice to say that I have had a lot of practice of technical writing!

I love learning, and I love sharing. What I learn I like to share through writing, as it also helps me solidify my understanding too.

Over the last 3 months, my posts have received around 75K views per month across medium and this blog. So the evidence suggests that my writings aren’t turning readers away at least!

So to help more people share their knowledge and insights, here are a few simple rules that I follow when I write.

Mind the “curse of expertise”

The most important rule of thumb is to always remember you are the expert of your domain. When you share knowledge & experience, you need to be mindful what assumptions you’re making of the reader.

Especially when you discuss the merits or problems of an approach. Always state your assumption and context explicitly up front. This helps the reader understand WHY you’re doing this, and the constraints you’re working with.

In the immortal words of Simon Sinek, start with why, which brings us to the next point.

Sell the problem, NOT the solution

“Brad, sell me this pen”
Like that great scene in “the wolf of wall street” where Di Caprio asked Jon Bernthal to sell him a pen.

Create the demand, then supply the solution.

Sell the problem to the reader. Help them understand why it’s a problem worth solving. The merits of your solution are irrelevant without an interesting and worthwhile problem.

Where possible I try to set out what a “good” solution would look like, and what properties it should have. After describing the solution I would then finish off with the tradeoffs I have to make. This would usually evolve around the pillars of cost, complexity and efficiency.

If you don’t define what “good” is up front, then it’s easy for cognitive biases to creep in. We often subconsciously bend the definition of “good” to fit our solution, and lose objectivity in the process. We all have this confirmation bias, there’s no escaping it. But defining “good” ahead of time helps keep us honest with ourselves.

Keep in mind that your solution might only work in specific contexts. If people adopt your solution without understanding the context in which it worked, then they risk failure. Worse yet, if the failures are not obvious enough, then you might have started another cargo cult

Keep it short

On medium, you can see how long your post takes to read and how many people read it start to end. Unsurprisingly there is a clear trend that longer posts have a lower read %.

I compiled the stats for my posts related to serverless and this is what I see.

This is reflected in my personal reading habits too. I tend to finish longer posts over several sitting as I often lose my attention span midway. I’m seldom able to finish a long post in one sitting, even if I ‘m really engaged by it.

What that means to you is that you should keep things short, punchy, and to the point. Don’t linger with your words and try to explain things to the Nth degree.

If need be, use bullet points, and keep each to one line.

Write the post, then read it back a few times. With each run, cut out unnecessary words or rephrase sentences to make them more concise.

For example, “to be or not to be, that is the question” might be vague and leaves a lot to the reader. The longer, more expansive version is actually far less clear!

Courtesy of Kevlin Henney’s talk “7 ineffective coding habits of many programmer” –

Be honest

Goes without saying :-P

Picture says a thousand words

Apply common sense, too many pictures is also not good.

Also, keep pictures relevant. We all love cat pictures, but too much of it (or used out-of-context) is off putting.

Start strong

I follow this advice when giving talks as well, and try to kick off a presentation or post with a strong message.

Think of your reader’s attention span as a currency. You have to earn the audience’s attention before you can spend them on technical discussions.


So that’s it, 6 simple rules that I follow whenever I write. The freecodecamp folks also have some very good advice for writing on medium.

I hope this post helps you improve your writing. If you have any suggestions on how I can improve my own writing style, please feel free to let me know via the comments below.

Happy Easter everyone!

Liked this article? Support me on Patreon and get direct help from me via a private Slack channel or 1-2-1 mentoring.
Subscribe to my newsletter

Hi, I’m Yan. I’m an AWS Serverless Hero and I help companies go faster for less by adopting serverless technologies successfully.

Are you struggling with serverless or need guidance on best practices? Do you want someone to review your architecture and help you avoid costly mistakes down the line? Whatever the case, I’m here to help.

Hire me.

Skill up your serverless game with this hands-on workshop.

My 4-week Production-Ready Serverless online workshop is back!

This course takes you through building a production-ready serverless web application from testing, deployment, security, all the way through to observability. The motivation for this course is to give you hands-on experience building something with serverless technologies while giving you a broader view of the challenges you will face as the architecture matures and expands.

We will start at the basics and give you a firm introduction to Lambda and all the relevant concepts and service features (including the latest announcements in 2020). And then gradually ramping up and cover a wide array of topics such as API security, testing strategies, CI/CD, secret management, and operational best practices for monitoring and troubleshooting.

If you enrol now you can also get 15% OFF with the promo code “yanprs15”.

Enrol now and SAVE 15%.

Check out my new podcast Real-World Serverless where I talk with engineers who are building amazing things with serverless technologies and discuss the real-world use cases and challenges they face. If you’re interested in what people are actually doing with serverless and what it’s really like to be working with serverless day-to-day, then this is the podcast for you.

Check out my new course, Learn you some Lambda best practice for great good! In this course, you will learn best practices for working with AWS Lambda in terms of performance, cost, security, scalability, resilience and observability. We will also cover latest features from re:Invent 2019 such as Provisioned Concurrency and Lambda Destinations. Enrol now and start learning!

Check out my video course, Complete Guide to AWS Step Functions. In this course, we’ll cover everything you need to know to use AWS Step Functions service effectively. There is something for everyone from beginners to more advanced users looking for design patterns and best practices. Enrol now and start learning!