You Talk Too Much

Written by: Timlah | Written on: 15 Jun 2025 | Estimated reading time: 4 minutes

---

Think you know your audience? Maybe not as well as you think.

I've been writing blog posts for a long time now, not just on this website, but also for my old projects. I've always been told my style is conversational and entertaining. I like hearing that, but it doesn't mean that writing style is appropriate for every content type I work on.

This is a shallow dive into communication and why verbosity isn't (always) helpful.

Knowing your audience

The wise words of Professor Oak rings true: "There's a time and a place for everything, but not now."

When I'm working on a ticket, I need to consider how I'm going to convey to everyone that my work is done, or how far along it is. I can write all of my thoughts in the ticket, but this is going to be really hard to follow. I, too, may get lost in the future about why I added in a sentence around the position of the Sun relative to Earth. I'm sure the reason for me adding that sentence will become clear, any day now*.

Ticket template

I have a really simple philosophy when it comes to ticket updates: Keep it brief. I do this by writing bullet point updates, which can look something like this:

**Today's Progress**
- Bumped the version to `x.x.x`
- Encountered compilation errors when bumping version
	- Resolved compilation errors:
		- Updated method signature
		- Added required implicit method
- Updated unit tests

**To Do:**
- Ensure all tests pass: Unit, Integration, Visual Regression, etc
- Share PR with team for review

The above is all I need in order to convey the things I encountered on the ticket, as well as what I have left to do. I have, however, seen people write long, long comments about what they've done, who they spoke to, why they spoke to them, how they communicated with those people and much, much more. It's not needed. It takes time for people to read if they need to come back to that ticket in the upcoming weeks, months or years.

I've struggled with communications within tech, because people love to talk. In some ways, this is people being passionate about their jobs and that is admirable and great! But you really do need to know your audience. If I'm reading your comment in a team channel, get to the meat and potatoes of what you want me to know. Maybe add a follow-up comment, if you need to share the additional context, but help me quickly get to what I need to know.

The faster your reader knows what they're supposed to get out of your writing, the better. In a blog post, I attempt to setup the premise of the article within the first paragraph. That way, if people decide they're not interested in the topic, they can click away. By contrast, I want people reading my tickets to know what's happening on that ticket right away. No preamble, nothing, just progress. I might have additional comments, but when people look at my tickets in the morning stand-up, I want them to not be bogged down by technical jargon.

Other Templates

Huh? You want to know more? Okay.

I write every blog post following a template. I write my blog posts in Obsidian, checking for spelling mistakes and re-reading my posts over and over.

I've written about Obsidian and the Templater plugin in the past, so if you'd like to know what that strange await command is, go check out why I think Obsidian is Underrated. But this shows why my blog posts tend to be structured the same way. Some text, some heading, maybe an image, some subheadings and so on. I feel this gives a familiarity and helps me structure my thoughts and feelings. I even pull this templated logic out to documentation, albeit I just have to shift my focus to being more concise.

As a last point, if you're in tech, then there's this constant desire for everything to be done fast. Get that website up and running, pronto. Get those comms out, make it snappy. There's this need for speed within development and I feel that we're forgetting the phrase more haste, less speed. If we go too fast, we're going to be making mistakes - Communication should not be rushed.

When you chat to someone at work about what you're working on, let them in on what you're going to talk about upfront. It'll help them so much more, rather than having to understand what you're saying, by eliminating the added filler that you hadn't filtered out. Tell them about the other stuff when that other stuff matters. If they need to know that other stuff, just take a moment to consider how braindumping all of that in one go will sound. Structure your thoughts, folks!

Thanks for reading, I feel I was adequately able to elucidate the consistent consequence of cultivating too much chatter. Let us proceed with the signing off of this blog post, wherein we utilise our regular catchphrase to clearly signify this is benevolently coming to an end:

Much love to all and happy tinkering - Timlah

* It, in fact, did not become clear why the position of the Sun relative to Earth was vital to that piece of work. I'm sure another 1,000 word comment will bring that to light.

p.s: Just in case you were wondering, the Obsidian theme I use is 80s Neon by Deathau. The theme can also be installed via Settings > Appearance > Themes | Manage > '80s Neon'.