Excerpts on Refactoring English

How to Write an Effective Software Design Document

Wed, 24 Jun 2026 00:00:00 +0000

A good design doc can save you years of development time. Writing a design doc forces you to think through important decisions before you waste time on the wrong implementation or paint yourself into a corner. It’s also the best way to coordinate design decisions among teammates and partner teams.

I’ve written design docs as a developer at Google, Microsoft, and within my own companies. The specifics vary, but the underlying principles remain the same. A design doc should articulate the hard problems you’re solving and help your teammates give you feedback.

Why Improve Your Writing?

Tue, 03 Mar 2026 00:00:00 +0000

I’ve worked as a developer for 20 years, and I’ve always cared about clear writing. When I join a new team, the first thing I do is ask to update the onboarding documents. As I ramp up on the team, I document what I learn and encourage my teammates to do the same.

Sometimes, other developers ask me why I invest so much into writing. Programming is technical, so why spend time on a “soft skill” like writing? Isn’t that why we have technical writers and product managers?

How to Get Meaningful Feedback on Your Design Document

Mon, 03 Nov 2025 00:00:00 +0000

You’ve spent weeks carefully writing a design document for your software project, but what happens next? How can you get useful feedback about it from your teammates? How do you prevent your design review from dragging on for months?

I’ve been through many design reviews in my career as both the author and reviewer, and I have a special fondness for effective reviews. Through trial and error, I’ve learned techniques that help the review process move smoothly and yield material improvements to the design.

Underused Techniques for Effective Emails

Wed, 16 Jul 2025 00:00:00 +0000

For software developers, there’s tremendous value in writing effective emails. Good emails save time, reduce misunderstandings, and earn you recognition within your company.

How to Write Compelling Software Release Announcements

Wed, 25 Jun 2025 00:00:00 +0000

A release announcement showcases how the user’s experience is better today than it was yesterday. That sounds obvious, but most release announcements seem to forget that there’s a user at all.

So many release announcements just enumerate new features in a way that’s totallly divorced from how real people use the software. The announcement is essentially just a changelog with better writing.

For example, here’s a “changelog” style of announcing a new feature:

How to Write Blog Posts that Developers Read

Thu, 27 Mar 2025 00:00:00 +0000

I recently spoke to a developer who tried blogging but gave up because nobody was reading his posts. I checked out his blog, and it was immediately obvious why he didn’t have any readers.

The developer had interesting insights, but he made so many mistakes in presenting his ideas that he was driving everyone away. The tragedy was that these errors were easy to fix. Once you learn to recognize them, they feel obvious, but some bloggers make these mistakes for years.

How to Write Useful Commit Messages

Fri, 07 Mar 2025 00:00:00 +0000

Effective commit messages simplify the code review process and aid long-term code maintenance. Unfortunately, commit messages don’t get much respect, so the world is littered with useless messages like Fix bug or Update UI.

There’s no widespread agreement about what makes a good commit message or why it’s useful, so I’m sharing my thoughts based on my 20 years of experience as a software developer.

An example of a useful commit message
What’s the point of a commit message?
Organizing information in a commit message
- Put the most important information first
- Use headings to structure long commit messages
What should the commit message include?
What should the commit description leave out?
Further reading

An example of a useful commit message

Here’s an example of a useful, effective commit message:

Passive Voice Considered Harmful

Fri, 31 Jan 2025 00:00:00 +0000

Your high school English teachers probably warned you that passive voice is dangerous and forbidden. Then, when you were an adult, some guy in a leather jacket told you that passive voice is cool and should be used whenever it’s desired.

Well, the tide has turned again. If you’re a software developer, stop using the passive voice.

Wait, what’s passive voice?

In English, sentences can have one of two structures: passive voice or active voice.

Rules for Writing Software Tutorials

Thu, 02 Jan 2025 00:00:00 +0000

Most software tutorials are tragically flawed.

Tutorials often forget to mention some key detail, preventing readers from replicating the author’s process. Other times, the author brings in hidden assumptions that don’t match their readers’ expectations.

The good news is that it’s easier than you think to write an exceptional software tutorial. You can stand out in a sea of mediocre guides by following a few simple rules.

Rules

Write for beginners
Promise a clear outcome in the title
Explain the goal in the introduction
Show the end result
Make code snippets copy/pasteable
Use long versions of command-line flags
Separate user-defined values from reusable logic
Use unambiguous example values
Spare the reader from mindless tasks
Keep your code in a working state
Teach one thing
Don’t try to look pretty
Minimize dependencies
Specify filenames clearly
Use consistent, descriptive headings
Demonstrate that your solution works
Link to a complete example

Write for beginners

The most common mistake tutorials make is explaining beginner-level concepts using expert-level terminology.