Tags: clarity

21

sparkline

Tuesday, March 9th, 2021

Content buddy

One of my roles at Clearleft is “content buddy.” If anyone is writing a talk, or a blog post, or a proposal and they want an extra pair of eyes on it, I’m there to help.

Sometimes a colleague will send a link to a Google Doc where they’ve written an article. I can then go through it and suggest changes. Using the “suggest” mode rather than the “edit” mode in Google Docs means that they can accept or reject each suggestion later.

But what works better—and is far more fun—is if we arrange to have a video call while we both have the Google Doc open in our browsers. That way, instead of just getting the suggestions, we can talk through the reasoning behind each one. It feels more like teaching them to fish instead of giving them a grammatically correct fish.

Some of the suggestions are very minor; punctuation, capitalisation, stuff like that. Where it gets really interesting is trying to figure out and explain why some sentence constructions feel better than others.

A fairly straightforward example is long sentences. Not all long sentences are bad, but the longer a sentence gets, the more it runs the risk of overwhelming the reader. So if there’s an opportunity to split one long sentence into two shorter sentences, I’ll usually recommend that.

Here’s an example from Chris’s post, Delivering training remotely – the same yet different. The original sentence read:

I recently had the privilege of running some training sessions on product design and research techniques with the design team at Duck Duck Go.

There’s nothing wrong with that. But maybe this is a little easier to digest:

I recently had the privilege of running some training sessions with the design team at Duck Duck Go. We covered product design and research techniques.

Perhaps this is kind of like the single responsibility principle in programming. Whereas the initial version was one sentence that conveyed two pieces of information (who the training was with and what the training covered), the final version has a separate sentence for each piece of information.

I wouldn’t take that idea too far though. Otherwise you’d end up with something quite stilted and robotic.

Speaking of sounding robotic, I’ve noticed that people sometimes avoid using contractions when they’re writing online: “there is” instead of “there’s” or “I am” instead of “I’m.” Avoiding contractions seems to be more professional, but actually it makes the writing a bit too formal. There’s a danger of sounding like a legal contract. Or a Vulcan.

Sometimes a long sentence can’t be broken down into shorter sentences. In that case, I watch out for how much cognitive load the sentence is doling out to the reader.

Here’s an example from Maite’s post, How to engage the right people when recruiting in house for research. One sentence initially read:

The relevance of the people you invite to participate in a study and the information they provide have a great impact on the quality of the insights that you get.

The verb comes quite late there. As a reader, until I get to “have a great impact”, I have to keep track of everything up to that point. Here’s a rephrased version:

The quality of the insights that you get depends on the relevance of the people you invite to participate in a study and the information they provide.

Okay, there are two changes there. First of all, the verb is now “depends on” instead of “have a great impact on.” I think that’s a bit clearer. Secondly, the verb comes sooner. Now I only have to keep track of the words up until “depends on”. After that, I can flush my memory buffer.

Here’s another changed sentence from the same article. The initial sentence read:

You will have to communicate at different times and for different reasons with your research participants.

I suggested changing that to:

You will have to communicate with your research participants at different times and for different reasons.

To be honest, I find it hard to explain why that second version flows better. I think it’s related to the idea of reducing dependencies. The subject “your research participants” is dependent on the verb “to communicate with.” So it makes more sense to keep them together instead of putting a subclause between them. The subclause can go afterwards instead: “at different times and for different reasons.”

Here’s one final example from Katie’s post, Service Designers don’t design services, we all do. One sentence initially read:

Understanding the relationships between these moments, digital and non-digital, and designing across and between these moments is key to creating a compelling user experience.

That sentence could be broken into shorter sentences, but it might lose some impact. Still, it can be rephrased so the reader doesn’t have to do as much work. As it stands, until the reader gets to “is key to creating”, they have to keep track of everything before that. It’s like the feeling of copying and pasting. If you copy something to the clipboard, you want to paste it as soon as possible. The longer you have to hold onto it, the more uncomfortable it feels.

So here’s the reworked version:

The key to creating a compelling user experience is understanding the relationships between these moments, digital and non-digital, and designing across and between these moments.

As a reader, I can digest and discard each of these pieces in turn:

  1. The key to creating a compelling user experience is…
  2. understanding the relationships between these moments…
  3. digital and non-digital…
  4. and…
  5. designing across and between these moments.

Maybe I should’ve suggested “between these digital and non-digital moments” instead of “between these moments, digital and non-digital”. But then I worry that I’m intruding on the author’s style too much. With the finished sentence, it still feels like a rousing rallying cry in Katie’s voice, but slightly adjusted to flow a little easier.

I must say, I really, really enjoy being a content buddy. I know the word “editor” would be the usual descriptor, but I like how unintimidating “content buddy” sounds.

I am almost certainly a terrible content buddy to myself. Just as I ignore my own advice about preparing conference talks, I’m sure I go against my own editorial advice every time I blurt out a blog post here. But there’s one piece I’ve given to others that I try to stick to: write like you speak.

Thursday, January 28th, 2021

How to be clear – gilest.org

Good advice for writing:

  • Think about what your readers might already know
  • Write shorter sentences, with simpler words
  • Constantly think about audiences
  • Communicate with purpose
  • Clear communication helps teams solve problems

Thursday, January 21st, 2021

Letters of exclusion

I think my co-workers are getting annoyed with me. Any time they use an acronym or initialism—either in a video call or Slack—I ask them what it stands for. I’m sure they think I’m being contrarian.

The truth is that most of the time I genuinely don’t know what the letters stand for. And I’ve got to that age where I don’t feel any inhibition about asking “stupid” questions.

But it’s also true that I really, really dislike acronyms, initialisms, and other kinds of jargon. They’re manifestations of gatekeeping. They demarcate in-groups from outsiders.

Of course if you’re in a conversation with an in-group that has the same background and context as you, then sure, you can use acronyms and initialisms with the confidence that there’s a shared understanding. But how often can you be that sure? The more likely situation—and this scales exponentially with group size—is that people have differing levels of inside knowledge and experience.

I feel sorry for anyone trying to get into the field of web performance. Not only are there complex browser behaviours to understand, there’s also a veritable alphabet soup of initialisms to memorise. Here’s a really good post on web performance by Harry, but notice how the initialisms multiply like tribbles as the post progresses until we’re talking about using CWV metrics like LCP, FID, and CLS—alongside TTFB and SI—to look at PLPs, PDPs, and SRPs. And fair play to Harry; he expands each initialism the first time he introduces it.

But are we really saving any time by saying FID instead of first input delay? I suspect that the only reason why the word “cumulative” precedes “layout shift” is just to make it into the three-letter initialism CLS.

Still, I get why initialisms run rampant in technical discussions. You can be sure that most discussions of particle physics would be incomprehensible to outsiders, not necessarily because of the concepts, but because of the terminology.

Again, if you’re certain that you’re speaking to peers, that’s fine. But if you’re trying to communicate even a little more widely, then initialisms and abbreviations are obstacles to overcome. And once you’re in the habit of using the short forms, it gets harder and harder to apply context-shifting in your language. So the safest habit to form is to generally avoid using acronyms and initialisms.

Unnecessary initialisms are exclusionary.

Think about on-boarding someone new to your organisation. They’ve already got a lot to wrap their heads around without making them figure out what a TAM is. That’s a real example from Clearleft. We have a regular Thursday afternoon meeting. I call it the Thursday afternoon meeting. Other people …don’t.

I’m trying—as gently as possible—to ensure we’re not being exclusionary in our language. My co-workers indulge me, even it’s just to shut me up.

But here’s the thing. I remember many years back when a job ad went out on the Clearleft website that included the phrase “culture fit”. I winced and explained why I thought that was a really bad phrase to use—one that is used as code for “more people like us”. At the time my concerns were met with eye-rolls and chuckles. Now, as knowledge about diversity and inclusion has become more widespread, everyone understands that using a phrase like “culture fit” can be exclusionary.

But when I ask people to expand their acronyms and initialisms today, I get the same kind of chuckles. My aversion to abbreviations is an eccentric foible to be tolerated.

But this isn’t about me.

Wednesday, January 8th, 2020

Guide to Internal Communication, the Basecamp Way

Writing solidifies, chat dissolves. Substantial decisions start and end with an exchange of complete thoughts, not one-line-at-a-time jousts. If it’s important, critical, or fundamental, write it up, don’t chat it down.

This one feels like it should be Somebody’s Law:

If your words can be perceived in different ways, they’ll be understood in the way which does the most harm.

Friday, January 3rd, 2020

Frank Chimero · Redesign: On This Design

Most experienced designers want concision—clear, robust, consistent, elegant systems that avoid redundancy. Concise designs are smoother to implement, faster to render, quicker to understand, and easier to hand-off and maintain. Achieving a simplicity with clarity means that you’re engaging with the fundamentals of the problem (and of your craft) at the correct fidelity. You’ve cut through complexity with insight, understanding, and committed decision-making. That third one is critical. A lot of complexity comes from an unwillingness to commit to the things that insight and understanding surface.

Tuesday, October 29th, 2019

Nicole Fenton | Words as Material

If we want design to communicate, we need to communicate in the design process.

I might get that framed.

Thursday, June 27th, 2019

Clarity and Style · Matthias Ott – User Experience Designer

Styling something is easy. Making something crystal clear is hard.

Wednesday, May 15th, 2019

Humanizing Your Documentation - Full Talk - Speaker Deck

The slides from Carolyn’s talk at Beyond Tellerrand. The presentation is ostensibly about writing documentation, but I think it’s packed with good advice for writing in general.

Thursday, February 28th, 2019

Getting help from your worst enemy

Onboarding. Reaching out. In terms of. Synergy. Bandwidth. Headcount. Forward planning. Multichannel. Going forward. We are constantly bombarded and polluted with nonsense speak. These words and phrases snag and attach themselves to our vocabulary like sticky weeds.

Words become walls.

I love this post from Ben on the value of plain language!

We’re not dumbing things down by using simple terms. We’re being smarter.

Read on for the story of the one exception that Ben makes—it’s a good one.

Tuesday, October 2nd, 2018

Use the words normal people use

When you’re struggling to write something that sounds clear and sounds human (two of the essential basics of a good blog post, I’d argue), just use the words normal people would use.

John Spencer: “There’s no bullshit like design bullshit” - Design Week

If we use jargon, we reveal our insecurity. If we use pretentious language, we expose our arrogance. But if we use language that anyone can understand, people are much more likely to value what we do.

Tuesday, March 6th, 2018

Wednesday, November 1st, 2017

Coding with Clarity · An A List Apart Article

Good advice on writing code that is understandable to your fellow humans (and your future self).

Monday, July 10th, 2017

Words

I like words. I like the way they can be tethered together to produce a satisfying sentence.

Jessica likes words even more than I do (that’s why her website is called “wordridden”). She studied linguistics and she’s a translator by trade—German into English. Have a read of her post about translating Victor Klemperer to get an inkling of how much thought and care she puts into it.

Given the depth of enquiry required for a good translation, I was particularly pleased to read this remark by John Le Carré:

No wonder then that the most conscientious editors of my novels are not those for whom English is their first language, but the foreign translators who bring their relentless eye to the tautological phrase or factual inaccuracy – of which there are far too many. My German translator is particularly infuriating.

That’s from an article called Why we should learn German, but it’s really about why we should strive for clarity in our use of language:

Clear language — lucid, rational language — to a man at war with both truth and reason, is an existential threat. Clear language to such a man is a direct assault on his obfuscations, contradictions and lies. To him, it is the voice of the enemy. To him, it is fake news. Because he knows, if only intuitively, what we know to our cost: that without clear language, there is no standard of truth.

It reminds me of one of my favourite Orwell essays, Politics and the English Language:

Political language — and with variations this is true of all political parties, from Conservatives to Anarchists — is designed to make lies sound truthful and murder respectable, and to give an appearance of solidity to pure wind.

But however much I agree with Le Carré’s reprise of Orwell’s call for clarity, I was brought up short by this:

Every time I hear a British politician utter the fatal words, “Let me be very clear”, these days I reach for my revolver.

Le Carré’s text was part of a speech given in Berlin, where everyone would get the reference to the infamous Nazi quote—Wenn ich Kultur höre … entsichere ich meinen Browning—and I’m sure it was meant with a sly wink. But words matter.

Words are powerful. Words can be love and comfort — and words can be weapons.

Thursday, June 22nd, 2017

Code clarity - Anthony Ricaud

Breaking down programming tasks into smaller chunks …and naming things.

I’ll take a piece of paper and write the function names I’m going to implement. Or I’ll do it directly in my code editor, with real functions or comments.

It allows you to focus on one problem at a time. When you’re writing those function names, you are thinking about what the code should be doing. When you’re implementing the functions, you are thinking about how the code should do it.

Tuesday, August 23rd, 2016

Why do pull quotes exist on the web?

There you are reading an article when suddenly it’s interrupted by a big piece of text that’s repeating something you just read in the previous paragraph. Or it’s interrupted by a big piece of text that’s spoiling a sentence that you are about to read in subsequent paragraphs.

There you are reading an article when suddenly it’s interrupted by a big piece of text that’s repeating something you just read in the previous paragraph.

To be honest, I find pull quotes pretty annoying in printed magazines too, but I can at least see the justification for them there: if you’re flipping through a magazine, they act as eye-catching inducements to stop and read (in much the same way that good photography does or illustration does). But once you’re actually reading an article, they’re incredibly frustrating.

You either end up learning to blot them out completely, or you end up reading the same sentence twice.

You either end up learning to blot them out completely, or you end up reading the same sentence twice. Blotting them out is easier said than done on a small-screen device. At least on a large screen, pull quotes can be shunted off to the side, but on handheld devices, pull quotes really make no sense at all.

Are pull quotes online an example of a skeuomorph? “An object or feature which imitates the design of a similar artefact made from another material.”

I think they might simply be an example of unexamined assumptions. The default assumption is that pull quotes on the web are fine, because everyone else is doing pull quotes on the web. But has anybody ever stopped to ask why? It was this same spiral of unexamined assumptions that led to the web drowning in a sea of splash pages in the early 2000s.

I think they might simply be an example of unexamined assumptions.

I’m genuinely curious to hear the design justification for pull quotes on the web (particularly on mobile), because as a reader, I can give plenty of reasons for their removal.

Friday, April 15th, 2016

Clarity 2016 Wrapup by Chris Coyier on CodePen

As well as compèring the event, Chris took the time to make notes at the Clarity conference, dedicated to all things patterny.

Tuesday, April 5th, 2016

Clarity Conf: Brad Frost

I wish I could’ve made it to the Clarity conference—I had a Salter Cane gig to play—but luckily for me, Brad took lots of notes.

Wednesday, August 12th, 2015

Use the words normal people use

When you’re struggling to write something that sounds clear and sounds human (two of the essential basics of a good blog post, I’d argue), just use the words normal people would use. The best way to find out what those words are is to try talking the thing through to someone who doesn’t know anything about it. Remember what you just said, then write that.

Sunday, March 30th, 2014

Hemingway

A useful text editor that analyses your writing for excess verbiage and sloppy construction. It helps you process your words, as it were.