Posted just now about writer’s checklists – so let’s post about the developer’s checklists here too!
As a developer, I maintained a checklist of troubleshooting tips.
I would have conversations like this:
Me: Any thoughts on what I could do next?
Colleague: Have you tried [something they also recommended last time]?
Me, embarrassed: Uh… no. I’ll try that. Writing that down this time! Thanks.
And I’d add that to my checklist.
For reasons unknown, developers assume that we are the last person in our organization who will ever encounter a specific problem.
We’re the last person our team will ever onboard, so we don’t need to document lessons learned during onboarding.
This error message won’t happen again, so there’s no need to note the steps we took to address it.
Nobody else will install or configure this product, so we won’t bother writing down the process we went through.
“I’m surely the last person to ever go through this process.” Photo by Christin Hume on Unsplash
And then we’re surprised when three days or weeks or months later, the same situation has come up again and we’re struggling to remember what we did last time.
Last page list
I kept my troubleshooting checklist starting on the back page of my notebook so I could always find it in a hurry.
The specific items on the checklist will vary from person to person, but they might include:
When did this code work last? Did it ever work?
What changed between when it last worked and now?
Can I reproduce the problem in another environment? How about another branch of my code?
What if I back out my last change?
Have I tried clearing the browser cache? (Ugh. I always forget.)
Did I push the change to the environment where I’m expecting it?
Am I getting an error? Search for the exact text of the error in the code, in Slack, on the web…
Some of the best writing tips I learned were from a summer class I took as a teenager. I’m still adding to my writer’s checklists, decades later.
However, I have mostly kept these checklists in my head. Whenever I realize that I have documentation stored in my head, I want to write it down.
First of all, the information in your brain is not searchable! Make it useful to others, and write. Part of why I’m writing a book, after all!
And second, the brain is a much better processing unit than it is a storage unit. Get all that excess knowledge out of your head and onto a more reliable “external drive” (like paper). Then you can free up mental space for things you can’t just go look up.
Here’s my basic checklist:
What’s sillier than putting “make to-do list” on a to-do list? This. Photo by Jakub Żerdzicki on Unsplash
Vary sentence beginnings. “She did this. She saw that. She said something. She blah blah blah.” Change it up!
Similar: vary sentence structure. Subject-verb, subject-verb, subject-verb… gets boring after a while.
Break up long sentences. If you’ve got more than one and/or/but, start to get suspicious that a sentence is perhaps too long.
However, it’s trendy these days to write entirely in short, choppy sentences, or even sentence fragments. I’m not a fan. Again, vary that sentence structure.
Avoid the passive voice. I don’t try to eliminate it entirely, but I often like my writing better in the active voice.
Use tenses deliberately. I tend to switch between the present and the past tenses, unintentionally. But people do that naturally, and it can invite the reader to relive a specific moment with you. It’s only a problem if I don’t like what I wrote.
Drop extra words. Instead of: “That is one of those things that I find myself doing a lot.” Try: “I do that a lot.” The tipoff: a group of words such as this, that, what, which, something, or one, hanging out together in a sentence. “This is one of those things which…”
Watch out for weak words. “Very” and “really” are rarely doing me any favors. I use them, but sparingly.
Clarify “this.” I learned this tip recently. Even if it’s pretty clear what you mean by “that” or “these,” it can be even clearer if you just say it. “That guideline is so useful,” vs. “That is so useful.” Or, “I learned this tip recently,” instead of “I learned this recently.”
Instead of “you should,” try “I learned.” Rather than telling people what to take away from my writing, I find it more helpful to share my takeaways and let readers draw their own conclusions.
A bulleted list helps break up blocks of text.
Read it out loud
I often read my writing out loud. If I can’t bring myself to read out loud for some reason, I’m reading silently, but imagining how it sounds. I think of this as reading something to myself loudly. 🙂
Here’s what I’m listening for as I read out loud:
Words I’ve repeated. “Oops, I say ‘unintentionally’ twice in this sentence…”
Does it sound like me?
Do I get lost, or bored? If I do, my reader will.
Do I trip over my words or have to start over mid-sentence? Red flag. Look for grammar errors, stray words, sentences you can break up, or unnatural phrasing.
How are the pieces fitting together? Does the flow from one idea to another make sense?
What’s my tone? If I’ve veered off into “smug” or “judging” that’s a warning flag for me.
Am I repeating myself? Does it serve my purpose to do so, if I am?
Did I say something other than what I wrote? If so, did I do that because it sounds more natural the way I said it? For example, I wrote “I do use them.” But when I read it aloud, I said “I use them” instead. It sounded better shorter. I changed it.
If you’re struggling to read something you wrote, or if you read it and have the fleeting thought: “huh, I have no idea what I just said,” that’s your brain trying to tell you there’s a problem.
I’m sure there are others that I’ve forgotten to list here! I might edit this as I think of more.
Was this helpful to you? Did you pick up something new?
