Tech Writing Cookbook - Writing tips for you & my future self
PreviousChecklist for documenting a medium to large scale system architectureNextThe good that comes with maintaining blogs
Last updated
Last updated
Posted on 09 May, 2021
This page is dedicated to things I try to follow as a tech writer and developer & how one can learn to do the same.
Credits: David Peril
Readers should nod their head yes to the headline, subheading, and first sentence. If they've made it to the third sentence, they're ready for an interesting and compelling story.
"Good writing is supposed to evoke sensation in the reader, not the fact that it’s raining, but the feeling of being rained upon." - Sol Stein
Great writers unlock the ELECTRICITY of sight. They give their readers a pair of Magic Binoculars.
Facts alone aren't enough. They’re too black-and-white. Readers yearn for stories, images, and anecdotes that make the information POP.
“It’s only by concentrating, sticking to the question, being patient, letting all the parts of my mind come into play, that I arrive at an original idea. By giving my brain a chance to make associations, draw connections, take me by surprise” — William Deresiewicz
I usually think about the layout of the post while doing boring chores (making food). Schedule time to think and hone your understanding of the problem.
During writing a draft, make sure to give control to your mind & let the words flow. Take it from Michael
Some of the points that help me land a decision:
Are people not aware of this idea? Is it buried deep down in the messy internet?
Is it hard to understand?
Does it help even 1 person?
Are the already available blogs/articles outdated?
What are the future implications after I write this post?
How long is it going to complete the final version of article?
Did it help me or not?
Quick internet search read top 5 results, then directly jump to 2nd page to see hidden gems
Go through all the StackOverflow answers & comments (same with GitHub issues)
Ask only friends who might have good insights on the idea, no pinging random people. Optionally check opinions of professionals on Twitter (a necessary evil).
As you are writing you will realise the gapping knowledge holes in your understanding. Your Inner self will prompt you on areas which you not good at.
The point is to not supress it, its helping you grow.
You can tie this with Socratic questioning
Three questions to ask yourself while editing:
Is this correct?
Is this complete?
Is this convincing?
