> ## Content Index > Fetch the complete content index at: https://www.bramadams.dev/llms.txt > Use this file to discover other available public pages before exploring further. # Actually Good Technical Writing Tips - URL: https://www.bramadams.dev/202212190220/ - Published: 2023-01-31T18:58:10.000Z - Updated: 2024-02-20T01:58:23.000Z - Author: Bram Adams - Tags: writing, content-creation, hxh [If you are in the writing game, do yourself a favor and read this blog post about writing for developers.](https://semaphoreci.com/blog/tips-to-write-for-developers?ref=bramadams.dev) 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](https://www.youtube.com/watch?v=HAnXIIv5He8&ab%5Fchannel=RadialbyTheOrchard&ref=bramadams.dev) ^58oqr1 - **don't** enjoy the little detours[\[1\]](#fn1) - 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](https://www.nngroup.com/articles/applying-writing-guidelines-web-pages?ref=bramadams.dev) to learn how people read online. Their conclusion, [which remains true](https://www.nngroup.com/articles/how-people-read-online/?ref=bramadams.dev), 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](https://www.nngroup.com/articles/how-little-do-users-read/?ref=bramadams.dev). ([View Highlight](https://semaphoreci.com/blog/tips-to-write-for-developers?%5F%5FreadwiseLocation=0%2F45%2F4%2F1%2F1%2F1%2F10%2F7%3A0%2C2%2F49%2F4%2F1%2F1%2F1%2F10%2F7%3A1&ref=bramadams.dev#:~:text=Make%20the%20post%20skimmable%0A%0A%0A%0ASince%201994%2C%2Cwords%20in%20a%20given%20article.)) --- > • **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](https://semaphoreci.com/blog/tips-to-write-for-developers?%5F%5FreadwiseLocation=0%2F0%2F57%2F4%2F1%2F1%2F1%2F10%2F7%3A0%2C0%2F4%2F57%2F4%2F1%2F1%2F1%2F10%2F7%3A59&ref=bramadams.dev#:~:text=Writing%20short%20%288%20words%20or%2Cparagraph%20in%20the%20first%20sentence.%29) --- > **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](https://semaphoreci.com/blog/tips-to-write-for-developers?%5F%5FreadwiseLocation=0%2F107%2F4%2F1%2F1%2F1%2F10%2F7%3A0%2C0%2F5%2F109%2F4%2F1%2F1%2F1%2F10%2F7%3A6&ref=bramadams.dev#:~:text=Never%20go%20for%20longer%20than%2Cthe%20following%3A%0A%0A%0A%0APicturesDiagrams%20or%20chartsCode%20snippetsListsHeadingsTables)) --- > **“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***](https://www.amazon.com/100-Ways-Improve-Your-Writing/dp/0451627210?ref=bramadams.dev).\*\* ([View Highlight](https://semaphoreci.com/blog/tips-to-write-for-developers?%5F%5FreadwiseLocation=0%2F0%2F135%2F4%2F1%2F1%2F1%2F10%2F7%3A0%2C0%2F2%2F1%2F135%2F4%2F1%2F1%2F1%2F10%2F7%3A1&ref=bramadams.dev#:~:text=%E2%80%9CThis%20sentence%20has%20five%20words.%2CWays%20to%20Improve%20Your%20Writing.))\*\* --- > **The language you use can either bring you closer to the reader or create distance.** ![Language can create a barrier between the writer and the reader.](https://wpblog.semaphoreci.com/wp-content/uploads/2022/04/can-cant.jpg) 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](https://semaphoreci.com/blog/tips-to-write-for-developers?%5F%5FreadwiseLocation=0%2F143%2F4%2F1%2F1%2F1%2F10%2F7%3A0%2C0%2F149%2F4%2F1%2F1%2F1%2F10%2F7%3A297&ref=bramadams.dev#:~:text=The%20language%20you%20use%20can%2Cwarmth%20into%20otherwise%20dry%20writing.)) --- > 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](https://semaphoreci.com/blog/tips-to-write-for-developers?%5F%5FreadwiseLocation=0%2F185%2F4%2F1%2F1%2F1%2F10%2F7%3A0%2C0%2F185%2F4%2F1%2F1%2F1%2F10%2F7%3A337&ref=bramadams.dev#:~:text=Once%20the%20clutter%20is%20controlled%2C%2Call%20paragraphs%20perfectly%20line%20up.)) --- > • **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](https://semaphoreci.com/blog/tips-to-write-for-developers?%5F%5FreadwiseLocation=0%2F0%2F0%2F199%2F4%2F1%2F1%2F1%2F10%2F7%3A0%2C1%2F3%2F199%2F4%2F1%2F1%2F1%2F10%2F7%3A142&ref=bramadams.dev#:~:text=Make%20writing%20a%20habit%3A%20find%2Cinto%20place%20a%20lot%20faster.)) --- ![https://bram-adams.ghost.io/content/images/2023/01/you-should-enjoy-the-little-detours.png](https://bram-adams.ghost.io/content/images/2023/01/you-should-enjoy-the-little-detours.png) you should enjoy the little detours.png [↩︎](#fnref1)