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 ❤️❤️❤️
Top comments (6)
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
Once , I heard that the developers love them invent new concepts and convert basic concepts in imposible concepts
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!
Finally someone said it, it's annoying how some articles or blogs use too much 'tech' terms or abstract words when teaching concepts. Im already banging my head against the wall understanding a concept and now they use too much abstract words just to teach it too us, the post is great btw.