Entries that are too short for full posts of their own, yet

Quick questions

“Quick questions” are just questions. The asker has intentions about the scope, but doesn’t actually decide the question’s scope. Labeling a question “quick” is both a crutch and a conversational wedge past defenses.

Instead of labeling a question as quick, write your question down, make it succinct but complete. Be appreciative for the answerer’s time and attention, but let the question exist honestly.

Communicating is a core part of the job

It’s very easy for software engineers to focus on the “writing code” part of the job. Companies, product orgs, bosses are frequent encouragers of this. We aren’t supposed to count lines of code, but, also, ship a lot.

Less emphasis is placed on communication, both written and verbal, as part of the job. Most often, it comes up when something has gone pear shaped and the message becomes a post-facto “we need to improve how we communicate.” Sometimes, more pointedly, “You need to improve how you communicate.”

The (actual or apparent) secondary importance of communication to code generation is a disservice. In point of fact, code is just one aspect of communication. Sure, communication via instruction to, many levels down, the CPU. But also, code is communication to and with other engineers. Surrounding and supporting that code is everything else about work. Negotiation, clarification, feedback, explanation. Without communicating effectively, the entire software engineering effort suffers. So, instead of treating it as an afterthought, proactively focus on improving it.

Express, then edit, your internal monologue

A frequently communication issue at work is a me or a colleague asking a question, making a request, or providing an observation, but not giving enough context for others to understand what’s actually being said. In the best case, follow-up questions are asked. In less optimal cases, no one asks any follow-up questions but maybe some folks in the audience make inaccurate assumptions. Our internal monologues fill-in the essential context for our thinking, but that doesn’t always get outwardly expressed when writing or speaking.

An easy start when drafting such a message offline is overwrite it with more detail than you think is required in order to get the essential context out. Then, review and edit out excessive detail. That’s a better shot at providing an audience with the essentials necessary to understand what you’re trying to convey.

Expand and explain your acronyms, text shorthand, and slang

Whenever you find yourself using shorthand, or abbreviations as you might in group chat, expand it. E.g. “IMO” should become “In my opinion.” This is particularly true for internal team or organizational abbreviations that, if you share outside the group, are not clear.

If there’s a pronoun for the primary object of discussion, take a moment and swap out the pronoun for its noun, instead.

Some programming concepts like DRY or REST are probably fine to use as they are. Same with JS vs. JavaScript or HTML vs. Hypertext Markup Language. CSS vs. Cascading Stylesheets, same deal. But, if your writing did expand these terms when you first use them, so much the better.

Writing vs. not writing

A very valid component of writing is not writing. Identifying the situations and circumstances where there’s nothing for you to add. You might note your own thoughts and the impulse to say something, but part of the economy of writing is figuring out the when of writing vs. not.