Part of my Knowledge Repository.
- Don’t begin by telling the reader why you wrote your piece - tell them why they should read it, and then do your best to prove yourself right.
- If you’re wondering whether you should write a piece at all, you probably should.
- Many articles begin with a human framing, even those about highly technical topics.
- Don't let a desire to be (or at least sound) literary get in the way of your point.
- Be sparing with pronouns in technical writing. It's better to repeat a noun than have it be unclear what "it" refers to.
- Your post should ideally still work without hyperlinks.
- You can often make a piece much clearer simply by reordering the words in its sentences.
- Don’t write “it was X and Y” when X and Y are pure synonyms. Prefer “it was a good outcome” over “it was a good and positive outcome”.
- Don’t use intensifiers like very, extremely, or incredibly.
- Don’t hedge unless you mean it. If you genuinely aren’t sure of something, say so. Otherwise just make your point; it’s OK if someone disagrees.
- Use a thesaurus, especially when you have another criteria you need your word to meet.
- Don’t write how you talk; write how you would sound on a well-edited, multi-take podcast.
- Tell your reader where your piece is going and why.
- Every subject needs levity, and some subjects are incapable of supporting it.
- Don’t make your toy examples too contrived; get as close to a real-life use case as you can.
- Make it clear which parts of your examples should be copied and learned from, and which are arbitrary or even bad choices.
- Don’t use vocabulary that some of your audience might not know without acknowledging it. If the concept matters, explain it; if it doesn’t then summarize it in half a sentence and say that the details aren’t important today. If the concept really doesn’t matter then consider dropping the fancy word altogether.
- Keep a list of writing by other people that you wish you had written
- When someone asks you a question, that’s a good excuse for a blog post
How I’m applying this
While producing a huge amount of writing is not my current priority currently, I believe this list is a great start to a kind of ‘writing checklist’ which I can use as an editing companion before publishing my work. I’ll be looking to combine this with the book ‘Elements of Style’ to more comprehensively capture some important rules about writing well.