Technical Writing Tips

Writing my React book has been humbling: I wasn’t as good a writer as a I imagined. Here’s some what I’ve learnt working with my editor.

Why, what, how

Start by describing the problem the thing solves. Then describe the thing. Then show how to build the thing.

Authors love showing off solutions, but you must first convince the reader there is a problem.

The abstraction ladder

Solutions described in general terms waste the reader’s time. An example can stand for a whole category. Show a button instead of writing ‘suppose the user generates an event by interacting with the interface.'

Sharpen the main points

Start with your main point. Structure the following text to support it. Then repeat the main point, so the reader remembers what the explanation was about.

Some sections of your text state a thesis, some provide arguments, all must work towards one goal: persuading the reader.