
Ask HN: What are good writing tips for software developers? - soneca
I am thinking about all the occasions a developer writes words related to writing code. Pull requests descriptions, email communication with colleagues (devs and non-devs), commit messages, specifications, documentation.<p>Eventually a technical article or blog post too. But I am mostly concerned about day-to-day needs of writing that every developer has.
======
DannyB2
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.

~~~
rdiddly
Agreed. Also complete sentences.

~~~
DannyB2
and capitalization

~~~
anotherevan
Capitalisation is very important, if for no other reason then it means the
difference between helping your Uncle Jack off a horse...

~~~
DannyB2
A comma could also be an invaluable tool in that situation. Properly used. And
Walmart has them on sale in one dozen packs.

------
StriverGuy
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...](https://www.amazon.com/Writing-Well-30th-Anniversary-
Nonfiction-ebook/dp/B0090RVGW0)

2) On Writing - Stephen King- [https://www.amazon.com/Writing-10th-
Anniversary-Memoir-Craft...](https://www.amazon.com/Writing-10th-Anniversary-
Memoir-Craft/dp/1439156816/ref=tmm_pap_swatch_0?_encoding=UTF8&qid=&sr=)

3) The Elements of Style - Strunk & White - [https://www.amazon.com/Elements-
Style-Fourth-William-Strunk/...](https://www.amazon.com/Elements-Style-Fourth-
William-
Strunk/dp/020530902X/ref=pd_lpo_sbs_14_img_0?_encoding=UTF8&psc=1&refRID=K0EXMXPXXTNQZ7K2AD0M)

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

~~~
soneca
I am reading " _Style: Lessons in Clarity and Grace_ ", have you read this?

EDIT: link to the book: [https://www.amazon.com/Style-Lessons-Clarity-
Grace-12th/dp/0...](https://www.amazon.com/Style-Lessons-Clarity-
Grace-12th/dp/0134080416)

~~~
itamarst
It's much more useful then Strunk & White in my opinion.

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

~~~
shubhamjain
These prescriptive writing tips do more harm than good. The crucial question
is not whether you have adhered to all the tips but if what you wrote sounds
good. Following writing advice without critically analyzing it often leads to
writing which feels overdone.

~~~
eropple
I can write you a sentence that sounds amazing. I can also write it with an
unclear pronoun antecedent and make a hash of its meaning.

When you know how to write, you can break the rules. Until you do, guard rails
keep you from looking like an idiot.

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

------
3pt14159
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.

------
falcolas
I treat writing like I do programming. My goal is to get the interpreter (i.e.
the reader) to properly parse and understand the idea I'm trying to convey. As
such, I try and keep everything simple and on point, freely go back and
refactor sentences which don't make sense, and read the content back in my
head to see if the words I wrote even make sense to me.

The only other rule I really use is to write for as low level of an audience
as I can. This helps to reduce confusion for the readers, not all of whom may
have the same vocabulary or "state" as you. You don't want to write about
concepts from CS 401 when your readers are in CS 101, especially if the CS 401
concepts are not required for understanding.

Oh, and avoid un-delimited sarcasm. It travels really poorly through the
internet; someone will always take it at face value.

------
a5huynh
One of my favorite classes in grad school was learning to write about complex
topics in a clear and concise way.

Hopefully these reading materials are still useful!

\- "Science of Scientific Writing"
[https://cseweb.ucsd.edu/~swanson/papers/science-of-
writing.p...](https://cseweb.ucsd.edu/~swanson/papers/science-of-writing.pdf)

\- "Style: Lessons in Clarity and Grace" [https://www.amazon.com/Style-
Lessons-Clarity-Grace-10th/dp/0...](https://www.amazon.com/Style-Lessons-
Clarity-Grace-10th/dp/0205747469/)

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

~~~
soneca
As a developer who received regular positive feedback on the quality of my
writing, I am starting a side-project to help developers like you. :)

This post is to try to get a more diverse opinion on what constitutes good
writing outside of my bubble.

Please check the kick-off post, maybe you find it useful:
[https://writingfordevelopers.substack.com/](https://writingfordevelopers.substack.com/)

~~~
tmaly
Thanks, how often would you send out an email for this newsletter?

~~~
soneca
My plan is to send it weekly, but with shorter texts than this first one.

The idea is to be more specific, like: "Tips for a good Pull Request
description", "Tips for a good feature deploy announcement email", "Tips for a
good user story".

What do you think? Any topic you are particularly interested?

~~~
alex_hitchins
I'm very interested in this - will be signing up. I've been told my
specification writing style is good if just a little repetitive. I appreciate
it's a technical document and somewhat dry, however keen to see ways I could
improve sentence structure.

Edit to say : Tips on effective email communication would be good. I seem to
either be too brief and appear curt or waffle on where I shouldn't.

~~~
soneca
Thanks, it will the topic next Monday! :)

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

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

~~~
paulcole
Never write a giant email. Nobody's going to read it.

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

------
ChristianGeek
Lots of good advice here. Here are a few more basic tips:

1\. Read it out loud when you're done. If it doesn't sound right, change it so
that it does.

2\. For the love of everything grammatical, please learn how to use
apostrophes properly. Especially its/it's, your/you're, and yours. "It's"
always means "it is." "You're" always means "you are." "Your's" is not a word.

3\. There is no shame in using a spellchecker. (There is often shame in not.)

4\. Know your audience. Don't use technical terms if you're writing for non-
technical users and don't dumb it down for a technical audience.

5\. Be concise. There's no need to prove you can use a dictionary or thesaurus
to stretch out a sentence or to try to sound more intelligent than you need to
be (it doesn't work anyway).

If you want a friendlier guide to grammar than some of the other books listed
in this thread (which you should also consider adding to your reference
library), check out _Grammar Girl 's Quick and Dirty Tips for Better Writing_
by Mignon Fogarty [https://www.amazon.com/Grammar-Girls-Quick-Better-
Writing/dp...](https://www.amazon.com/Grammar-Girls-Quick-Better-
Writing/dp/0805088318)

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

~~~
V-2
> _read good writing_

That's sort of a Catch-22 right there. Can you tell if "your favorite SF
novel" represents good writing without having a grasp on what constitutes good
writing to begin with?

Is writing like cooking (where you don't really need to cook well yourself to
be able to tell)?

~~~
ambivalents
By virtue of it being your favorite, I would think it's doing something right.
But glibness aside, you could think about as you read: Is it fully engaging
you? Is it communicating a complex idea in a simple and/or novel way? Is it
making you feel something? Does it make you want to do something? These are
all good markers, because writing is really just about communicating ideas
well.

And if you don't trust your own judgment, you could look up some of the time-
tested classics. Some of my favorites: The Great Gatsby, To Kill A
Mockingbird, 1984 (fiction); Warren Buffett/Berkshire Hathaway shareholder
letters (business/sales writing).

~~~
V-2
> _By virtue of it being your favorite, I would think it 's doing something
> right_

That something doesn't have to be the quality of writing as such - eg. I can
enjoy a somewhat sloppily written book if the idea behind the plot is
captivating and compelling

------
garganzol
Hemingway App helps a lot:
[https://www.hemingwayapp.com/](https://www.hemingwayapp.com/)

~~~
52-6F-62
I was going to submit this as well. There's room for improvement with it, but
it really is great and a good launching point for reconsidering the structure
of your writing. Especially business writing or comms.

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

------
ivan_ah
If you're writing a long text (over 2 pages), you should invest the time to
proofread it properly, and maybe get it read by a friend or colleague. When
the ideas in a text are not clear and logically structured, it can be
perceived as disrespect to the readers.

One thing that really helps me to catch typos in my own writing, is the text-
to-speech utility built into Mac OS X. It makes it really easy to "hear"
typos. Here is a doc with screenshots that explain how to set up a keyboard
shortcut for this:
[https://docs.google.com/document/d/1mApa60zJA8rgEm6T6GF0yIem...](https://docs.google.com/document/d/1mApa60zJA8rgEm6T6GF0yIem8qpMmnaBFYOgV32gdMc/edit?usp=sharing)

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

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

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

------
agentultra
If you're an emacs user, try [https://github.com/bnbeckwith/writegood-
mode](https://github.com/bnbeckwith/writegood-mode)

~~~
lucozade
> writegood

This made me wince. I know it's perfectly acceptable American but that one's
definitely a low blow for an aging Englishman.

~~~
OhSoHumble
I'm fairly certain that the name of the project is tongue-in-cheek; it's not
uncommon to use "${X} good" as a comedic expression of poor English. For
example, "I done code good."

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

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

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

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

------
br377
The key to good communication is brevity

~~~
pklausler
"Omit needless words."

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

------
moltar
Tools: Grammarly

------
sleepychu
Don't be afraid of being terse.

