Search for a command to run...
The mid-ness of Surprising Simplicity
I'm a professional Software Developer and Developer Relations Manager.
My first love will always be Ruby but I'm writing a lot of JavaScript these days. I specialise in Automated Testing and work at Sauce Labs.
I truely believe that crafting Software is how I can best make the world better for its inhabitants, and I love educating and mentoring folks to who'd like to do the same.
No comments yet. Be the first to comment.
In Tokyo, I fell in love with a Robot
Or, a Gentlehacker's Guide to Releasing a Component as a Library
How ADHD folks can start their year off right.
Infrastructure, DevOps, and why they're tedious
A Tech Writing Tip, from your #DevRel Friend; It's not a good look to define people as surprisingly capable when describing how usable a system is:
"Even non-developers can use!"
"Even your Mum could do!"
"Can even be interpreted by end-users"
I call this Surprising Simplicity and it's dreadful.
Using "non" frames developers as being a special class of people, which makes your readers feel good... But it implies that people who aren't in that class aren't as worthwhile. You're typically writing as part of the in-group, the developers in question. Don't make fun of those who are not du monde; That's no more then simple bullying.
You also want to avoid the universal truth vibes given off by "Even". This form is reliant on the assumption that the group described would typically be incapaple of making use of your product. You're positioning these folks as incapable so that It feels like a win that these folks can make use of your product. If that's not true, that's kinda gross. If it is true, is that an inherent property to the problem, or to the solution? What's the difference? The latter tends to be an assumed reality; something that products make true by assuming it's true. (A much more visceral (and harmful) example of this is explained by the video ASSUME THAT I CAN released for World Down Syndrome Day 2024).
The "Mum" example also includes bonus of propagating some sexist and ageist stereotypes about women, older people, and parents. Best to skip this one entirely.
"Gives end-users flexible reporting, and developers the fine-grained controls you need"
This isn't just better for inclusivity, it's better, period. People read tech writing because they have a problem & want to not. As an author, you're aiming to be convincing in your ability to make said problem go away. By presenting your solution as a tool they can use, it invests the reader with feelings of agency and capability. A focus on surprising simplicity doesn't do this; Instead, it shifts the focus to other, apparently less capable people.
"Simpler then programming a VCR"
"Easy enough for your 'bad-with-computers' friend"
(NB: A VCR was a device for recording & playing back TV shows; like a bad-quality CD for video.)
(NB: CDs were a flat plastic disc which encoded music by laser etching; Like a offline version of Limewire.)
(NB: Limewire was...)
Archetypes help scaffold our thinking. This is why personas are useful for product decisions, user stories and marketing strategies. They're just as useful in tech writing, with two caveats.
Firstly, people tend to use stereotypes instead of archetypes. What's the difference? Let us compare
"Self-Service customers are not skilled at statistics, have short result timeframes and a tendency to escalate support tickets."
with
"Karen wants to speak to the manager again because she doesn't understand regressions."
Archetypes have their relevant traits, skills and behaviours explicitly defined. They are (or at least should be) formed from emotionally neutral observations. Stereotypes, on the other hand, are only indexical of their traits; That is, the presence of the stereotype implies the traits. Typically they do so by creating a caricature, over-emphasizing certain behaviours and ascribing them to a certain kind of person, often in ways that reflect existing prejudices and relies on emotional implications.
Secondly, when referring to archetypes by name, you risk over-reliance on internal information. I have often experienced folksrefers to a market segment or persona by their companies' internal name, to the confusion of external parties. A mid-market customer probably doesn't know they're mid-market; a vendor might not know that you use architect in a way they use business analyst. This one is easy to avoid; Make the traits and behaviours specific instead of relying on names. (We're back to indexicality.)
Then I invite you to consider: These forms are #techwriting#cliches. Your copy will resonate more strongly and read more fluently without them, and your audience will walk away thinking about your product, not your writing.
Additionally, we are living in the algocene, an epoch where vaugely understood advertising junkie information systems shuttle human attention around like hummingbees doing a speedrun, yet our ability to find accurate information appears worse then ever before. It is entirely conceivable that a simple "Ahoy Computer: How do I {x}" will lead one of your non-developer, four-kids-and-a-dog customers to your writing, leaving them with the gross sense that they're lesser beings; and your product with one less user.
Liked this? Hated it? Comment down below!
