How to Write an Effective Software Design Document
Best practices for writing a design doc based on my experience working as a developer at Google and Microsoft.
Excerpts
These are sample excerpts from the Refactoring English.
Why Improve Your Writing?
Programming is a technical pursuit, so why should we spend time on a "soft skill" like writing? Isn't that why we have technical writers and product managers?
Underused Techniques for Effective Emails
For software developers, there's tremendous value in writing effective emails. Good emails save time, reduce misunderstandings, and earn recognition from upper management.You can drastically improve your emails with a few simple techniques, but too few developers know about them.
How to Write Compelling Software Release Announcements
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.
How to Write Blog Posts that Developers Read
Software bloggers can make the same mistakes for years that prevent readers from discovering their writing. I know because I'm one of them. Over time, I've learned techniques that help some blog posts succeed and the pitfalls that cause others to languish in obscurity.
How to Write Useful Commit Messages
Unfortunately, commit messages don't get much respect, so the world is littered with useless messages like "Fix bug" or "Update UI." Effective commit messages simplify the code review process and aid long-term code maintenance.
Passive Voice Considered Harmful
When software developers use passive voice, they often introduce ambiguity and create confusion. Active voice is the better default.
Rules for Writing Software Tutorials
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.