Today I Learned

Appearance

Tech Writing Cookbook - Writing tips for you & 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

    Michael-writing-wisdom

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

Accepting your inner critic ​

  • 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

Editing ​

Three questions to ask yourself while editing:

  1. Is this correct?
  2. Is this complete?
  3. Is this convincing?

Resources ​

Written while 🙇🏽‍♀️