KISS 😘: Keep It Simple & *Short* - My Tech Writing Principle
Tags: discuss, writing, productivity, beginners
Published: 2019-09-11 19:04:56

I'm a true believer of *ain't no body got time*. So I try very hard to keep my post simple and short (less than 3 mins read). This post shares my approaches to a KISS writing principal.

# Break it down, and down

Whenever I find myself writing something longer than 3 minutes, I try to look back and see if I can break it down into multiple posts.

For example, I once came across a post idea of "3 simple ways to improve SEO for your site". But during drafting, I figured the 3 ways mentioned in the post were not tightly related, so I decided to make 3 posts instead, each explaining only one approach. 

This way, each of my posts feels more focused, with a cleaner title, and helps readers gain a very specific piece of information in a short amount of time.

# Why > How

I prefer talking about why to how. Why? Because there are already too many how-to articles online: how to build an app, how to use an AWS service, etc. But these are ONLY helpful if the reader understands the tech and the concept. And in my opinion there are far less good articles explaining the concepts and contexts around the tech. I was a tech beginner once and I understand how lost I felt when I blindly followed a tutorial without knowing the big picture.

Since I only had 3 mins to explain something, I'd focus on telling the big picture: why the tech existed, where it shines (or not), how it compares to alternatives, and leaving the 'how' part to the readers themselves (or with links).

For example, there are hundreds of online articles talking about how to setup up Babel and Webpack, but after reading many of them I still didn't understand why I needed one or both of them. So I wrote my own:

{% link https://dev.to/getd/wtf-are-babel-and-webpack-explained-in-2-mins-43be %}

# Use simple, non-tech words

If you haven't already, please read the *What Amazon Says* vs. *Let's make easier to understand* part from this awesome post:

{% link https://dev.to/lewismenelaws/what-is-aws-a-guide-for-beginners-p4l %}

Kudos to AWS for making it harder to understand their products (aka hiding their cashier)!

Tech posts shouldn't read like a thesis, even when targeting experienced audiences. On the other hand, sometimes even experienced developers don't understand those abstract buzz tech words. Personally, I always find it helpful when concepts are explained in plain words, with real-world examples. This makes the post simple and easy to read. A sample post:

{% link https://dev.to/getd/x-www-form-urlencoded-or-form-data-explained-in-2-mins-5hk6 %}

# Be Relative

I always feel *there is nothing new-new in tech*. Almost any 'new' tech, no matter how fancy it seems on the surface, can always be related to some predecessors or alternatives that date years or even decades back.

When explaining a 'new' or 'fancy' tech, it's always helpful to relate or compare to some pre-existing tech that readers are more familiar with. This allows readers to leverage what they already know and link the new concepts on top of it. It also saves me from explaining the concept from scratch, which helps KISS. E.g.,

{% link https://dev.to/getd/webhook-is-just-a-fancy-way-of-saying-event-driven-server-to-server-api-calls-explained-in-1-min-4e23 %}

----

**OK I will stop here at the 3-min mark. I love writing KISS posts to help people get excited and learn about tech. Please [follow my twitter @tech_bos](https://twitter.com/tech_bos) so you will know when I publish a new post!**

**Writing is a very subjective topic. To all the awesome writers in dev.to community: What writing principals do you follow? Please share your pro tips in the comment below ❤️❤️❤️**