Ask HN: What are good writing tips for software developers?

- "Start with why." (I use 3 layers of why, some more, some fewer.)

- Get it out, then go back and reverse the order of the sentences in each paragraph, so each one begins with the point you were getting to.

- Kill your babies. Any turn of phrase you are working around to keep it in, or make it work is not as good as you think.

- Read a lot of quality, edited writing. The Economist, Financial Times, Telegraph, and sometimes even the Guardian. Avoid cloying, sing-song, editorial prose that is full of jargon and cliches.

Source: am a writer who codes.

If you are proofreading something and it absolutely has to be perfect - do all your normal proofreading, grammar checking, etc. Then when you think it is good, read it once, backward, for spelling errors. We can develop blind spots and skip over things when reading them in the normal left-to-right fashion. If you read it starting at the end all the way to the beginning, your brain has to consider each word independently, with no context.

I have caught countless spelling errors after being sure a document contained none by reading it backwards.

2. Keep paragraphs short.

3. Unless you're part of the story, don't use "I" or "we".

4. Avoid gendering an abstract person. "Flight attendant" over "stewardess" / "they" over "he".

5. For long reports put the three to five points in a numbered list on the first page and bold one sentence or fragment per point. This makes the report easier to forward to upper management. Upper management is where the bonuses come from.

6. Learn the precise definition of words. A software virus is not the same thing as a software worm. Being at a higher risk does not mean that the potential outcome has gotten worse (see risk vs hazard).

7. Re-read / edit your piece (log(estimated number of people reading it) + 5) number of times before publishing. This only applies to actual writing. Don't waste your time doing this for Hacker News comments.