A common goal of many people, including myself, is to be understood. To not only be heard but listened to. For the person receiving to 'get' what the first person is saying.

This is trickier with the written word compared to a verbal conversation. You can't usually rely on quick feedback techniques like 'reflective listening' or similar to correct misunderstandings or gain clarification. Writing clearly can also improve the accessibility of your content.

So if good written communication is your goal, then there are a few things you can employ:

  • Correct spelling
  • Appropriate grammar
  • Proofreading (ideally by another person)

I was reminded of this recently when an old work colleague (hi Simon!) reached out to let me know that I had a typo in my GitHub 'About Me' page. He knew me well enough to know that I love this kind of feedback! It caused me to review the text again myself, and I discovered a second error, so it was good to get them both fixed.

Another example that comes to mind is an ebook I purchased a couple of years ago from a well-known book publisher. I won't name the title, but it relates to .NET, and almost from the first page I was encountering grammatical errors. I don't blame the author for this, but rather the book publisher. My understanding is that these should have been caught in the editing phase of publishing. It doesn't reflect well on the publisher (or the editor) that they somehow missed addressing this, and makes me more cautious about buying other books from them. The result was a book that I found hard to read. Sentences didn't flow, and comprehension was more of a challenge than it should have been. I gave up reading the book in the end as it was too distracting.

I've recently been going back and running cspell over my older blog posts. It's embarrassing to find numerous spelling errors in old posts that have been sitting there for years. At least I can fix them. A little while ago, I migrated my blog from Blogger to self-hosting on GitHub using Jekyll, with all the posts now being written in Markdown. I have the Code Spell Checker extension installed in Visual Studio Code. For newer posts, spelling errors should be flagged in the editor.

Microsoft Word has had grammar checking built-in for quite a while, and I thought I'd have a search to see if there was something similar for Visual Studio Code (the editor I use to write my blog posts in). It looks like Rahul Kadyan has written an unofficial Grammarly extension. I just installed it, and check out all the extra squiggles as I was writing this page in the screenshot below!

Do take the time to review Grammarly's privacy policy. They run "as a service", so all your text for grammar checking will be sent to them, so make sure you're comfortable with that.

Screenshot of Grammarly warnings

Look, it's spotted another repeated word ("an an old work") already!

The extension has some limitations. Some of the corrections are only available to paid Grammarly users (it took me a bit to figure that out - signing in with a free account doesn't seem to have any benefit).

It is interesting to compare that to copying and pasting the text into Microsoft Word. Fewer squiggles, but it has flagged the repeated word.

Screenshot of Microsoft Word grammar/spelling warnings

Tools are great, but the skill is knowing when to use them and when it is ok to ignore them.

Getting at least one extra pair of eyes to proofread your text is probably the best idea. Only this week, I asked a colleague to review something I'd written to confirm that my intentions were being conveyed correctly before sharing it more widely. It's less useful for my blog, being my thoughts, but I have used it in the past. While my blog content is hosted on GitHub, the repository is private, as sometimes I might have future posts or drafts that aren't ready to be publicly viewable.

In conclusion, my goal is to create clear and understandable content. Do reach out in the comments if you find cases where I've fallen short of that - I'm sure there are many (probably some I've still overlooked in this post!). With your help, I hope you find it easier to understand what I'm trying to say.