Just change it

Amber and I often have meta conversations about the nature of learning and teaching. We swap books and share ideas and experiences whenever we’re trying to learn something or trying to teach something. A topic that comes up again and again is the idea of “the curse of knowledge“—it’s the focus of Steven Pinker’s book The Sense Of Style. That’s when the author/teacher can’t remember what it’s like not to know something, which makes for a frustrating reading/learning experience.

This is one of the reasons why I encourage people to blog about stuff as they’re learning it; not when they’ve internalised it. The perspective that comes with being in the moment of figuring something out is invaluable to others. I honestly think that most explanatory books shouldn’t be written by experts—the “curse of knowledge” can become almost insurmountable.

I often think about this when I’m reading through the installation instructions for frameworks, libraries, and other web technologies. I find myself put off by documentation that assumes I’ve got a certain level of pre-existing knowledge. But now instead of letting it get me down, I use it as an opportunity to try and bridge that gap.

The brilliant Safia Abdalla wrote a post a while back called How do I get started contributing to open source?. I definitely don’t have the programming chops to contribute much to a codebase, but I thoroughly agree with Safia’s observation:

If you’re interested in contributing to open source to improve your communication and empathy skills, you’re definitely making the right call. A lot of open source tools could definitely benefit from improvements in the documentation, accessibility, and evangelism departments.

What really jumps out at me is when instructions use words like “simply” or “just”. I’m with Brad:

“Just” makes me feel like an idiot. “Just” presumes I come from a specific background, studied certain courses in university, am fluent in certain technologies, and have read all the right books, articles, and resources. “Just” is a dangerous word.

But rather than letting that feeling overwhelm me, I now try to fix the text. Here are a few examples of changes I’ve suggested, usually via pull requests on Github repos:

They all have different codebases in different programming languages, but they’re all intended for humans, so having clear and kind documentation is a shared goal.

I like suggesting these kinds of changes. That initial feeling of frustration I get from reading the documentation gets turned into a warm fuzzy feeling from lending a helping hand.

Have you published a response to this? :

Responses

2 Shares

# Shared by Simon Willison on Friday, February 1st, 2019 at 4:54pm

# Shared by Morgan Roderick on Friday, February 1st, 2019 at 9:34pm

25 Likes

# Liked by Caspar ⚡️ Hübinger on Friday, March 2nd, 2018 at 8:05pm

# Liked by Frank M. Palinkas on Saturday, March 3rd, 2018 at 12:08am

# Liked by Lea Verou on Saturday, March 3rd, 2018 at 9:04am

# Liked by Mike McCallister on Wednesday, March 7th, 2018 at 11:03pm

# Liked by Chris DeMars on Wednesday, March 28th, 2018 at 3:35pm

# Liked by G. Taylor McKnight on Friday, February 1st, 2019 at 5:04pm

# Liked by Ben Bodien on Friday, February 1st, 2019 at 5:04pm

# Liked by Mark IJbema on Friday, February 1st, 2019 at 5:04pm

# Liked by Michael Bishop on Friday, February 1st, 2019 at 5:04pm

# Liked by Keith Devens on Friday, February 1st, 2019 at 5:04pm

# Liked by Simon Willison on Friday, February 1st, 2019 at 5:04pm

# Liked by Nik Fletcher on Friday, February 1st, 2019 at 5:04pm

# Liked by Mohamed Usif on Friday, February 1st, 2019 at 5:53pm

# Liked by David Blaikie on Friday, February 1st, 2019 at 5:53pm

# Liked by Matt Henry on Friday, February 1st, 2019 at 5:53pm

# Liked by Zander on Friday, February 1st, 2019 at 6:28pm

# Liked by Flávio Juvenal on Friday, February 1st, 2019 at 6:53pm

# Liked by Nicolas 🖕 Chambrier on Friday, February 1st, 2019 at 7:58pm

# Liked by Peter WM on Friday, February 1st, 2019 at 8:59pm

# Liked by Honza Javorek on Friday, February 1st, 2019 at 8:59pm

# Liked by Morgan Roderick on Friday, February 1st, 2019 at 9:57pm

# Liked by Dr Mark Everitt on Friday, February 1st, 2019 at 10:31pm

# Liked by 𝘥𝘉/𝘶 on Saturday, February 2nd, 2019 at 12:36am

# Liked by Jj on Saturday, February 2nd, 2019 at 8:25am

# Liked by Hynek Vychodil on Saturday, February 2nd, 2019 at 10:18am

Related links

Tagged with

Previously on this day

9 years ago I wrote Design sprinting

Packing a whole lotta learning into just five days.

10 years ago I wrote Responsive Day Out tickets tomorrow

24 hours ‘till tickets go on sale.

11 years ago I wrote Async, Ajax, and animation

Hijax, Youjax, we all jax for Pjax.

12 years ago I wrote Oh, what a Responsive Day Out that was!

Out of the park.

16 years ago I wrote See me speak

Past and future.

21 years ago I wrote Going to the movies

Being Oscar season, this is normally the time for looking back at the films of the past year, singling out the best for praise and the worst for derision.

23 years ago I wrote Information Wants to Be Worthless

Here’s a great article by Bruce Sterling who’s going to be speaking at the South by Southwest festival in his native Austin.

23 years ago I wrote Cross-Platform Testing

There’s a new article up at A List Apart on cross-platform testing on the Mac.