Writing advice

A program manager’s job is one of coordination and communication. And that communication is almost always in written form. This page collects the writing advice I’ve published.

• Stop writing like an engineer — Put the important part at the beginning of your post or email. Don’t assume people will read the whole thing.
• AIANYF: Acronyms & Initialisms Are Not Your Friends — Acronyms can be confusing when they’re unfamiliar to your reader. Err on the side of explaining, even if you don’t think you need to.
• It’s better to be clear than correct — Your prose is not code; it will not fail because you forgot a semicolon. Prefer being understood to strict adherence to grammatical rules.
• Be clear about who does what — If you’re not clear about who is supposed to act, people will assume that it’s not them. Be clear so everyone knows what to expect.
• Words mean things — Choose your words carefully. You want people to discuss the facts, not the wording.
• Footnotes and asides are a warning — Overuse of footnotes, commas, em dashes, and parentheses suggest your writing may be unclear. Keeping sentences focused helps your reader.
• Use your tools, but write like you — We live in a time when we’re awash in tools (often free) that aid writing. You miss out when you don’t take advantage of these tools.
• Just because you write it, that doesn’t mean they’ll read it — You can lead a horse to water, but you can’t make it drink. What happens if you write all of those wonderful words and they don’t get read?

In addition, here are other useful writing resources I’ve found:

• Technically We Write — A community site focused on technical writing advice and tooling.
• Write documentation that actually works for your community — “[G]ood documentation remains the best communication tool for groups and projects. This is especially true considering that projects tend to get bigger over time.”