Notes & TILs
Search…
Tech Writing Cookbook - Writing tips for you and my future self
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.

Writing hooks: "Get 3 yes's in 30 seconds".

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.

Verbose thinking is necessary

β€œ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
    ​
    ​

Validating an Idea

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?

Know when to stop researching βœ‹οΈ

  1. 1.
    Quick internet search read top 5 results, then directly jump to 2nd page to see hidden gems
  2. 2.
    Go through all the StackOverflow answers & comments (same with GitHub issues)
  3. 3.
    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).

Resources

Last modified 1mo ago