How frustrating is it when you're reading a poorly written article about a topic you're interested in? So frustrating! I'm trying to write more clearly so I never have to put you through that.
Writing is crucial to growth in engineering. At the level of senior (and especially staff/principal) engineer, strong writing becomes less of a nice-to-have and more of an expectation. As your reach grows, communicating within your team shifts towards getting alignment across teams and disciplines. That means getting ideas brewing in your head out into the world clearly and concisely, stating the knowns, unknowns, benefits and drawbacks for everyone involved.
That's no small task, and I don't think I'm great at it (yet). Here's what I'm trying.
Be direct
My stream of consciousness is not direct. I'm all over the place, writing in circles... but then it's time to clean up! As I said in my last post post, once I see the words on the page, it's easier for me to work with them. At that point I can make sure they're saying the right thing and building towards my point.
A few things I'm guilty of (and working on):
- Going on tangents
- Repeating myself
- Multiple ideas in one sentence
- Weak words
- Repeating myself
I'll usually spend paragraphs on tangents only to remove them during editing. I repeat myself without realizing it. I want to make sure I'm building a clear theme and removing words that make the message weaker. My default is to pepper my sentences with "I think"s and "Maybe just"s. Get rid of 'em.
And when I'm not paying attention, I have a tendency to string my sentences together, stuffing a few different ideas into one long stream of words, not giving the reader's brain a chance to rest (and usually adding one or two parentheticals in there for good measure, to really make the reader work at keeping track)... opting for ellipsis or a dash instead of a period—I rarely use a semicolon in order to not seem pretentious (or misuse it)—finally winding my way to a conclusion with the original point watered down in the tributaries of the main flow.
Just use shorter sentences. One idea at a time. Maybe go easy on the metaphors.
SCQA
One thing I've been experimenting with is the SCQA framework. I like the simplicity. When you spell it out it almost sounds too obvious to be useful, but it's a reminder that communicating doesn't have to be complicated.
- Situation: The objective facts
- Complication: What's changed, or what's causing problems?
- Question: Usually "What should we do about it?"
- Answer: A strategy that fully resolves the complication
Here's a simple example:
I've started writing more lately in an effort to practice and improve (S), but my writing isn't as clear as I want it to be (C). How can I get better (Q)? Focus on simple sentences with fewer weak words and tangents, and less repetition (A).
Not only is it clear, but you can read measurable results right within the answer. By watching each of those points over time I can determine if I'm trending in the right direction.
Here's a hypothetical example that's much larger in scale, and would require buy-in across many teams:
We have a monolithic codebase that has grown to thousands of files (S). We want to deploy more frequently, but because we deploy batches of changes at once, reverting one change often holds up deploys for hours. Also, breaking changes often happen unintentionally because dependency contracts aren't explicit (C). What should we do? (Q) Invest in a large-scale decoupling effort, making dependencies explicit with APIs and versioned libraries and giving teams control of their own deployment process (A).
There might be a lot of complexity behind a simple answer, and more complications will likely arise, but the strategy (and the writing) is clear. There are only four ingredients, simple like a good recipe (What did I say about metaphors?? And parentheses!!).
I'm only scratching the surface of SCQA, watch the talk for more!
Until finally
I'm not sure if any of this is actually making me better at writing, but it's good to have more tools. Sometimes you have to overuse a tool before finding a good balance, it's all part of the process.
Reading about SCQA, it reminded me a little of one of Pixar's storytelling rules:
Once upon a time there was _____. Every day, _____(S). One day _____(C). Because of that, _____. Because of that, _____. Until finally _____(A).
It's good for me to remember that no matter what I'm writing, I'm always telling a story. Even if it's technical, I have to make it compelling. I always want the reader (that's you!) feel like it was time well spent.
