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

As a developer myself, I have wanted to improve my writing skill. I have found an older copy of the The Pyramid Principle that I am working through. The whole premise of the book is to better structure your ideas using the pyramid pattern.

I recommend getting three books and to begin writing at least 500 words per day distraction free (technical, fiction, stream of conscious):

1) On Writing Well - William Zinser https://www.amazon.com/Writing-Well-30th-Anniversary-Nonfict...

2) On Writing - Stephen King- https://www.amazon.com/Writing-10th-Anniversary-Memoir-Craft...

3) The Elements of Style - Strunk & White - https://www.amazon.com/Elements-Style-Fourth-William-Strunk/...

The two most important points are concise style and active voice. Both of these habits are critical for SEs to write concise emails, specs and commit messages. You will even see improvement in more casual day to day interactions (via slack, SMS etc).

Some general pieces of advice that I think apply to all writing:

- Write like you would speak. Think of your writing as an extended conversation with other developers.

- Use the active voice wherever possible.

- Strive for clarity and simplicity over overly-complicated industry babble. The smarter you try to sound, the harder you will fail. Of course, there will be some amount of jargon you will rely on, which is fine considering your audience, but even with technical writing the Mark Twain axiom holds: don't use a $5 word where a $0.50 word will do.

- The best writing doesn't feel like writing. Take what you've written and read it out loud (to yourself or a friend). Rewrite until there's a natural rhythm and flow to your words.

- Don't be afraid of shitty first drafts. Dump out all your ideas without fear of judgment (no one's going to look!). Then go back and re-shape, re-word, cut, etc. I think of it like a sculptor and clay - your first draft is just a gathering of all the clay. The following revisions are about molding and shaping it for your intended audience.

- Finally, read good writing. Whether it be well-communicated emails or your favorite SF novel, pay attention to what other good writers are doing and try to emulate that.

If you're an emacs user, try https://github.com/bnbeckwith/writegood-mode

Writing is like backups. If you haven't done a backup restore, then it's not a real backup.

Similarly, if someone can't read what you wrote and then explain it back to you in their own language and concepts, your writing hasn't passed muster.

There's a reason there are always acknowledgments to draft-readers in books and YC essays.

Good writing is a result of good editing.

The two pieces of writing feedback I've received that I often regret not following:

- Most adverbs are superfluous. I am as guilty of ignoring this as anyone, but most cases where you say "generally" or "usually" you're undermining your point and the use of "very", "extremely", etc. are hyperbolic and breathless and make it easier to regard what you're writing as unserious.

- Avoid pronouns unless the antecedent is unmistakable. The use of "it" should immediately be a reason to re-read that sentence and the one before it for clarity.

I think there is a distinction between formal writing (article, blog post, docs, specs) and informal writing (commit messages, emails, pull request descriptions).

I wouldn't apply formal writing strategies to commit messages, they would be way too verbose. And I have different requirements for pull requests descriptions than I do for specifications.

I'm not sure where to start with helping you, it's a big question! If there's one thing that has always helped me it's re-reading what I've written; Write something, read it top to bottom (out loud, even), revise it, and repeat.

Hemingway App helps a lot: https://www.hemingwayapp.com/

Parsimony. Cut out the fat. Read Elements of Style for tips.

Also, read more and write more. You can only get better by doing more.

I suggest plugging all of your writing into Grammarly and HemingwayApp!

Writing improves from improved comprehension resulting from increased reading, writing, conversation.

So, make sure you are getting better at understanding the needs of the user and communicating them.

Have conversations with users - Solve problems that you have and make it available to others.

Solve others problems by learning about them and helping them.

The key to good communication is brevity

A preposition is a very bad word to end a sentence with.

But only a fool would begin or end a sentence with the word but.

And only a total idiot would begin or end a sentence with the word and.

Anyway, you should never use the word 'anyway'. Even worser to use 'anyways'.

And never utilize the word 'utilize' when you could utilize the word 'use' instead.

Your doing it wrong if you're sentences confuse the words your and you're.

There are two many people doing it wrong too get to upset about confusion over to, too and two.

Don't be afraid of being terse.

Pretend like you're explaining things to a smart 10 year old. Keep your sentences well structured, only use jargon and abbreviations when necessary, and don't be afraid to repeat yourself for clarity. It helps to give as much background knowledge as possible.

Always proofread what you write. Always. Even if it’s a short text message or a giant email.

Keep your audience firmly in mind. Your dev colleague will probably warrant more technical detail than your non-dev colleague (but the non-dev colleague might need a different kind of detail). If the audience is future-you, you'll remember a lot less of the context of the message than you assume you will. You'll want to include sufficient detail to bring someone up to speed, link it to an issue in a bug tracker, etc.

But the kind of detail, appropriate level of detail, and presentation will change, depending on who is supposed to read it. An IM message to another dev will look very different from customer-facing documentation.

Easiest wins:

- "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.

Have a very specific audience in mind while writing. Even go so far as to write your content in an email editor with a friend or two similar to your intended audience in the To: field.

Good writing tip for anyone:

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.

1. Try to have an identified audience. It makes the piece easier to write because the language selection will be straightforward and you'll be able to avoid explaining concepts that the audience is already familiar with so it will be shorter.

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.

Get a good style guide, read it, and stick to it. I like the Dictionary of Modern American Usage because its recommendations are presented with justifications.

0. Give a damn. You're already doing this step, which is great!

1. Every first draft is crap. Edit. Edit again. I do this for everything — design docs, doc comments, HN comments, email, tweets. Writing is editing.

2. Have a clear audience in mind that you are writing for, ideally a single person, sympathetic to your topic, but choose whatever audience makes sense.

3. Treat your audience with respect and try to give them as much value as you can in return for the effort, time, and attention you are asking of them. When you edit to distill and clarify your concepts, you are transferring effort from them onto yourself, and they'll thank you for it.

4. Unless you're writing for a venue that explicitly requires it, formality is overrated. People will remember your writing better if they have some emotional connection to it, and that requires an informal human element.

Commit messages should start with a verb, and complete the sentence "If you apply this commit, it will..."