Actually Good Technical Writing Tips
Some of my favorite tips -- emphasis mine:
tl;dr:
- be bold about using bold
- short headers, few letters
- jump cuts work in text too
- variety in sentence structure makes for good reading, variety on a plate makes for good eating
- hey little reader lemme whisper in your ear ^58oqr1
- don't enjoy the little detours[1]
- build an unhealthy addiction to writing for people you'll never meet
Make the post skimmable
Since 1994, Jakob Nielsen and John Morkes have been conducting studies to learn how people read online. Their conclusion, which remains true, is that readers rarely read the whole page.
Online readers are active. They like to scan and skim, picking the information they need. Most readers will read only 20% of the words in a given article. (View Highlight)
• Writing short (8 words or less) and interesting headers that tell a story. Don’t go deeper than H2 or H3.
• Write short paragraphs of less than 5 lines.
• Use bold or italic fonts to emphasize important parts of your text.
• Separate sections with plenty of whitespace.
• State the idea behind each paragraph in the first sentence. (View Highlight
Never go for longer than three paragraphs without using one or more of the following:
• Pictures
• Diagrams or charts
• Code snippets
• Lists
• Headings
• Tables (View Highlight)
“This sentence has five words. Here are five more words. Five-word sentences are fine. But several together become monotonous. Listen to what is happening. The writing is getting boring. The sound of it drones. It’s like a stuck record. The ear demands some variety.”
— Gary Provost, 100 Ways to Improve Your Writing.** (View Highlight)**
The language you use can either bring you closer to the reader or create distance.
Write using I, we, and you. Don’t be afraid to express your opinions and views. Imagine you’re speaking to a close friend and don’t write anything you wouldn’t say in a conversation.
There are instances in which rules or style guides recommend not using such pronouns. Even so, you can still maintain a friendly tone by writing in the first person for the first draft and removing it on a second pass. It may sound like extra work, but it brings warmth into otherwise dry writing. (View Highlight)
Once the clutter is controlled, it’s time to check for missing links in your reasoning and places where you branched off the topic. Each paragraph should build on the previous one without any detours. This is very careful work that demands composure. Expect the draft to undergo multiple revisions until all paragraphs perfectly line up. (View Highlight)
• Make writing a habit: find the best time to write and make a habit of writing every day. Some people like the morning and night owls write best under the cover of darkness.
• Change the scenery: go to a cafe or the park. The library works too.
• Go for a walk: turn off the computer and do some exercise. Some of the best ideas I’ve had came to me when I wasn’t at the desk.
• Sleep on it: if you’re overwhelmed, let it rest for a few days and focus on other articles. When you come back, things will fall into place a lot faster. (View Highlight)