Beyond Writing Code

Category: language

Writer’s checklists
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?
2025-08-19
Did I chat with an AI?
I try to avoid posting about AI, but today I found myself wondering: did I just chat with an AI?

Trying to decide which of several products to purchase online, I used the company’s website chatbot, which transferred me to “Vanessa” for further assistance.

Was Vanessa real? I found myself evaluating every line.

The overly-enthusiastic and strangely polished parts? That’s probably AI.

But what about…
- The natural-sounding, competent, useful responses?
- The grammatical errors?
- The inability to remember bits of context from earlier in the conversation?
- Delays where the “agent is typing” and I’m waiting…
- …but then I get an “are you still there?” a minute later while I’m typing?
- The occasional complete nonsense, sort of an on-topic word salad?
What’s wild to me is that I have experienced all of those things in the days before AI chat, when you could be reasonably certain you were talking to a human. So, on one hand, any of these could be a human behind the wheel.

As if AI chatbots had a physical incarnation with a hand

But then again, maybe AI would say: “How is you’re day so far?” If so, was the grammar error deliberately inserted, to make it sound more human? Or did AI just learn from a lot of grammatically incorrect training data?

Humans of yore

Once upon a time, you chatted (phone or text) with a human. They either knew how to help, or they would have you hold while they talked to someone else on your behalf. You could picture someone sitting in an office somewhere, spinning their office chair around to ask the senior person at the cubicle behind them.

Later, you chatted with a human who generally didn’t know how to help, but who could follow a flowchart of common questions. I worked in tech support, I get it. 90% of the calls are answered by the flowchart.

Unfortunately, those people would often not recognize when you were off the flowchart. I might say “step 3 of your instructions refers to a button that doesn’t exist,” and they’d just send me the link to the same instructions I was already following.

When they ran out of flowchart, they’d send you to tier 2. But even the flowchart person was still someone sitting in an office somewhere.

“The button doesn’t exist? That’s not on the flowchart.” Photo by Arlington Research on Unsplash

They might be following a script. But when it said “Agent is typing…” on the screen, they were at least assembling a reply from various bits of canned text with a little original text thrown in.

Where’s my person?

It was never clear to me how much “Vanessa” was controlled by a human operator. If at all.

I hope for the sake of that company that there was at least some human oversight to prevent inappropriate responses.

But, at best, I imagined someone monitoring multiple chats to make sure the AI responses weren’t going off the rails. Would they even need to know the product? Maybe their software could be doing some realtime sentiment rating to highlight if the user is getting frustrated.

The contrast was striking when, later in the day, I had a chat with “Julian” from Microsoft’s online sales chat feature. Aside from one overly enthusiastic greeting (on the order of “It’s an absolute delight to assist you today! How can I help you make your business more successful?”) the conversation… just felt normal.

The wording and grammar weren’t perfect. But they didn’t seem unprofessional, they just seemed human.

Microsoft likely has access to the best AI a company can get. If I had to pick a company that might have AI so good they could fake me out, they’d certainly be on my list of candidates.

But I feel like Vanessa’s response to “I honestly could not tell if I was talking to a real person or an AI” might have been something more… AI-sounding.

What would an AI say if asked that, anyway?

I couldn’t get claude.ai to be deceptive about it, even hypothetically. But I did get it to tell me what a human could say to reassure. I wanted an AI-generated example to contrast with Julian’s response above.

“Ha, I get that question sometimes! I do use assistance with my writing to make sure I’m being as helpful as possible, but there’s definitely a human behind these messages.”

Well done, Claude. No need to escalate to tier 2 support.
2025-08-06
Hotdogs and scrum
In the midst of a recent LinkedIn discussion about whether scrum is a methodology or a framework, I considered a few questions:
- Do we even know if people agree on definitions of terms like methodology?
- If people haven’t established agreement on the definitions, is there any point to having the argument? (For that matter, even if they do agree on the definitions, what’s the benefit of determining the answer?)
- Furthermore, if they disagree on the definitions, is it necessarily true that one (or both!) of the people is “wrong” about what the terms mean? Is there a single “true” definition for these terms? (I’m going with no.)
Geeks are often quite opinionated. I am sure some of my friends could hardly finish the first sentence of this post before needing to tell me whether scrum is a methodology or a framework, expounding upon their definitions of these terms. And some would accept no counterarguments. They know the true definitions of these terms and anyone else is wrong.

It reminds me of this question: Is a hotdog a sandwich?

Unsplash has some seriously unappealing photos of hotdogs. Is there a hotdog under that pile of stuff? One of them looked like it had tuna salad on it. Ew! And some of them looked barely cooked?? Come on people! Hats off to Ball Park Brand, whose photo this is. The first three photos that I considered using were all theirs.

I’m imagining myself at a cookout with two people arguing about whether a hotdog qualifies as a sandwich. Carry on. I’ll be over here eating a hotdog while I watch you argue.

One of my dad’s favorite questions was: “what are you going to do with this information?” Once you’ve decided if the hotdog is or isn’t a sandwich, are you going to do anything differently?

Let’s say you argue it isn’t a sandwich because there aren’t two separate pieces of bread and it’s not getting cut in half. Or maybe you argue that it is a sandwich because it’s a filling with bread on the outside to make it easy to hold. So what? Does that change what you put on it or how you eat it?

I feel the same way about scrum. I don’t really care if it’s a framework, a methodology, a set of practices, a bunch of ideas, or a cat on a unicycle juggling a set of printed-out Jira issues.

I gather that people are concerned because methodology implies that one must follow one rigid set of rules in order to do scrum correctly. My response: it does? I just think of “methodology” as a “way of doing stuff.” I’m probably wrong.

But just like with the hotdog, it just doesn’t matter for me. Even if there is a single right way to do scrum (which I doubt, doesn’t sound very agile to me!), I don’t care. I’ll check that way out, but ultimately I’m going to do what works for my team.

People. Do what works for you. I once ate a hotdog between two halves of a slice of bread, when I ran out of hotdog buns. It was fine.

I think the only time I want to know if scrum is “a methodology or a framework or what” is when someone asks me how to define scrum.

Which actually happened a few days ago! My aunt saw “scrum” on Wordle. (We all knew it was a rugby thing, but, as a software developer, I felt I should elaborate on its use in my field.)

“Scrum is… um…”

This is where I start to go for words like “thing” because what are my own definitions of “framework” and “methodology,” anyway? I’m not sure. Not that my aunt would have argued with me.

“Scrum is a way of working for development teams,” I told my aunt. Or so I like to imagine. Because in reality my mind spun into an extended lecture on agile and modern software development practices. But that was way, way more than was called for.

So instead, I just stammered awkwardly, then I turned to my husband to see if he could rescue me with a concise way of describing scrum. Alas, he did not rescue me. Not bad for two developers who have been practicing scrum for years, including me with my PMI-ACP certification. Yeah!

Fortunately, I don’t think my aunt was actually looking for details. She just wanted to assert that “scrum” seemed a little on the obscure side to be fair game for Wordle. We didn’t need to agree on a definition here either.

I apologize if this post made you hungry.

If you’d like to read more of my writing, I’d love to share! Sign up below for my email newsletter. May contain food analogies.
2025-06-27
Language learning

My Romanian coworkers were impressed when I started learning Romanian. I’d say “bună” (hello), complete with the ă, and they’d be shocked by even this basic effort.

What confused me, though: several of them insisted that Romanian was “hard”. I wasn’t sure at first how vehemently to disagree. I think of English as being a hard language to learn, partly because its mixed ancestry makes it fail to be consistent in its behavior. Take through, tough, dough, cough, plough, and thought, for example. Six different ways to say “ough” already.

Photo by Bruno Martins on Unsplash

It could be that I just have an advantage here. Romanian is, no surprise from the name, a romance language, as are French and Spanish. I studied French for 5 years, Spanish for about a year, and I have a smattering of German as well.

After about a year of Romanian, I recently switched to Haitian Creole (Kreyòl Ayisyen). Kreyòl is especially fun for someone with a background in French, because so many of the words are similar in pronunciation but different in spelling. Fwomaj, for example (fromage in French and cheese in English).

And then the other day, out of curiosity, I tried a bit of Polish. I am about 50% Polish in ancestry, after all. My grandfather would mutter a few numbers in Polish now and then when playing cards.

Jestem kobietą, says Duolingo. Uh oh. We’re on familiar territory with jestem (I am), but we’re already in a whole new place with kobietą (a woman). It didn’t get easier from there.

And that’s still a language with a familiar-ish writing system. I did dip my toe into Hindi on Duolingo for like… two days. In that time, we’re nowhere near using words, we’re just getting the sounds of a few characters down. I gave up because it was just too challenging for me to see the differences between symbols on my tiny phone screen.

Considering all that, then, Romanian might have been one of the easiest possible choices for me. It uses a mostly familiar alphabet. The pronunciation system is one-and-done: learn the full set and you’ve got pretty much the entire language (no “six ways to say -ough”). A lot of the grammatical concepts and words are familiar to me from either French or Spanish.

I have gone back to Kreyòl for now. Here’s one thing that’s blowing my mind about Kreyòl at the moment:

mwen manje – I eat
ou manje – you eat
li manje – he/she eats
nou manje – we eat
yo manje – they eat

Uhh. I was just starting to get used to Romanian’s ability (like Spanish) to drop pronouns and know who we’re talking about by how the verb is conjugated. Completely the opposite here!

I love seeing stuff like that.

2025-05-01