wriiting

Writing clearly and concisely is really tough.

It’s all too easy to fall into long, flowy sentences with multiple phrases, separated with commas, layers of meaning developing upon each other.

Irony intended.

Long sentences aren’t inherently bad, I don’t think – but they do lend themselves easily to ‘waffle’. It’s easy, or at least easier, to lose track of the meaning when they meander on for so long. I think what makes them difficult for me to avoid, though, is that they reflect how I think: one thought leads to many other branches, deepening or broadening the meaning, many of which are important and deserve a mention. It’s a very natural way of writing.

Sentences don’t need to be short to be clear. But short sentences often come across as clearer. They sort of ‘compartmentalise’ the infirmation into very distinct chunks. It’s in a much more obvious way than long sentences, where you may need to scan entire lines to pick out the core parts.

Then again, short sentences one after the other can feel abrupt and abrasive. It’s like you’re being bombarded. It doesn’t really read that nicely either. And it suffers from the same issue in that the content can be very dense – because of course, density is independent of length, really.

As with all things, I think a healthy balance is best – plus, context matters hugely.

Technical documentation is someplace it really matters, I think. You want to convey critical information to the developer as efficiently as possible.

But to this end, I think paragraphs of text really aren’t the most effective medium. If it’s code, showing the source code or an example is massively beneficial – it’s almost like a picture, 1000 words. Break up the text with:

• Lists
• Tables
• Diagrams
• Sections
• Emphasis
• Colour!

[!Tip] And split off extraneous content into distinctly indicated sections that can be directly skipped.

This is part of the reason why I love type hinting so much, because I can easily see what type I should be expecting to use, without needing to scan large bullet point lists. It’s a really concise but effective form of conveying key information.

One of the indicators of AI-generated content (at time of writing) is excessively verbose and winding content. It just doesn’t know when to stop, y’know?

Concision is an endeavour. It takes effort to condense things down effectively, while preserving value and meaning. Eventually, it becomes more effort than it’s worth, or you lose more than you gain. It’s exactly like compression!

The shorter you want it, the more effort it takes. You have to get harsher and harsher with what you cut away.[^poetic]

[^poetic]: Woah, poetic. Unintended!

Perfection is attained not when there is nothing more to add, but when there is nothing more to take away.

Love it. But taking away too much can be very real. The filler ‘fluff’ that goes in the long sentences, sure it could be optimised away – but those couple of characters can make something flow so much nicer.

Once again, writing is hard. Writing with concision and clarity is a careful game of balance, context and intent.

Hopefully that wasn’t too difficult to understand!