Eventually a technical article or blog post too. But I am mostly concerned about day-to-day needs of writing that every developer has.
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.
"Ending a sentence with a preposition is something up with which I will not put."
Don't write lead when you mean led. (I see this a lot in exec and other bios on company sites.)
Here's a small Python tool I wrote to help with stuff like this - it can easily be customized to add more suggestions of your own, from this thread or elsewhere:
Cut the crap! An absolutely essential tool for writers:
https://jugad2.blogspot.in/2015/07/cut-crap-absolutely-essen...
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).
EDIT: link to the book: https://www.amazon.com/Style-Lessons-Clarity-Grace-12th/dp/0...
I noticed a while ago a trend for commit messages to be in the active voice and present tense. Seems to make them more concise and read better / clearer. Started doing that myself on my projects.
- 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.
When you know how to write, you can break the rules. Until you do, guard rails keep you from looking like an idiot.
- "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.
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.
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.
Hopefully these reading materials are still useful!
- "Science of Scientific Writing" https://cseweb.ucsd.edu/~swanson/papers/science-of-writing.p...
- "Style: Lessons in Clarity and Grace" https://www.amazon.com/Style-Lessons-Clarity-Grace-10th/dp/0...
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/
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?
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.
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.
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.
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...
- 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.
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)?
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).
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
I think for the purposes at hand, you don't need any expertise in writing to tell whether you want to write short emails with some stuff lifted from a given author.
The larger structural aspects of writing a good novel are overlooked by a lot of people, and a lot of people will declare someone a "good author" when every character in their stories are an author stand-in, things appear and disappear for no reason, there is no symbolic or mythic resonance in the story, and every other major structural error that can be made, simply because they like the sentence-by-sentence style of the author or the author has snappy wordplay that they like. That taste is more rare, but also only slightly relevant to the question of whether you can write a 500-word email to the executive team about how important it is to not cut your project.
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.
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...
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.
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.
This made me wince. I know it's perfectly acceptable American but that one's definitely a low blow for an aging Englishman.
Also, read more and write more. You can only get better by doing more.