loading...
getd.io/ - Postman without native apps

KISS 😘: Keep It Simple & *Short* - My Tech Writing Principle

techbos profile image TechBos😎 Updated on ・3 min read

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:

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:

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:

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.,


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 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 ❤️❤️❤️

Posted on by:

techbos profile

TechBos😎

@techbos

Tech builder and writer. Twitter: @tech_bos, @getd_io. Creator of https://getd.io - A free, online REST API builder that works with CORS. A Postman alternative without native apps.

getd.io/ - Postman without native apps

A free, online REST API builder that works with CORS. A Postman alt. without the native apps.

Discussion

markdown guide
 

I’m learning to write about my tech experiences and this post has been a valuable guide. To add to that as a tip: I personally find myself writing a series to break long posts down into related shorter separate ones.

 

Writing a series sounds like a great idea too!

 

I love "X is just Y" posts. Slack is just pretty IRC, people! 😁

 

Good point! And Teams is just a not-so-pretty Slack =P