1–10 of 70 posts
Eventually a technical article or blog post too. But I am mostly concerned about day-to-day needs of writing that every developer has.
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).
- 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.
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 fin…
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)?
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.
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-Four…
EDIT: link to the book: https://www.amazon.com/Style-Lessons-Clarity-Grace-12th/dp/0...
- 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 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.