This old article from Chris is evergreen. There’s been some recent discussion of calling these words “downplayers”, which I kind of like. Whatever they are, try not to use them in documentation.
Tuesday, April 6th, 2021
Saturday, April 3rd, 2021
Always refreshing to see some long-term thinking applied to the web.
Monday, September 14th, 2020
Trys ponders home repair projects and Postel’s Law.
As we build our pages, components, and business logic, establish where tolerance should be granted. Consider how flexible each entity should be, and on what axis. Determine which items need to be fixed and less tolerant. There will be areas where the data or presentation being accurate is more important than being flexible - document these decisions.
Saturday, November 16th, 2019
An interesting project that will research and document the language used across different design systems to name similar components.
Friday, July 19th, 2019
Monday, July 15th, 2019
This is a great how-to from Darius Kazemi!
The main reason to run a small social network site is that you can create an online environment tailored to the needs of your community in a way that a big corporation like Facebook or Twitter never could. Yes, you can always start a Facebook Group for your community and moderate that how you like, but only within certain bounds set by Facebook. If you (or your community) run the whole site, then you are ultimately the boss of what goes on. It is harder work than letting Facebook or Twitter or Slack or Basecamp or whoever else take care of everything, but I believe it’s worth it.
There’s a lot of good advice for community management and the whole thing is a lesson in writing excellent documentation.
Thursday, May 23rd, 2019
After a fun and productive Indie Web Camp, I stuck around Düsseldorf for Beyond Tellerand. I love this event. I’ve spoken at it quite a few times, but this year it was nice to be there as an attendee. It’s simultaneously a chance to reconnect with old friends I haven’t seen in a while, and an opportunity to meet lovely new people. There was plenty of both this year.
I think this might have been the best Beyond Tellerrand yet, and that’s saying something. It’s not just that the talks were really good—there was also a wonderful atmosphere.
Marc somehow manages to curate a line-up that’s equal parts creativity and code; design and development. It shouldn’t work, but it does. I love the fact that he had a legend of the industry like David Carson on the same stage as first-time speaker like Dorobot …and the crowd loved ‘em equally!
During the event, I found out that I had a small part to play in the creation of the line-up…
Three years ago, I linked to a video of a talk by Mike Hill:
A terrific analysis of industrial design in film and games …featuring a scene-setting opening that delineates the difference between pleasure and happiness.
It’s a talk about chairs in Jodie Foster films. Seriously. It’s fantastic!
Marc saw my link, watched the video, and decided he wanted to get Mike Hill to speak at Beyond Tellerrand. After failing to get a response by email, Marc managed to corner Mike at an event in Amsterdam and get him on this year’s line-up.
Mike gave a talk called The Power of Metaphor and it’s absolutely brilliant. It covers the monomyth (the hero’s journey) and Jungian archetypes, illustrated with the examples Star Wars, The Dark Knight, and Jurassic Park:
Under the surface of their most celebrated films lies a hidden architecture that operates on an unconscious level; This talk is designed to illuminate the techniques that great storytellers use to engage a global audience on a deep and meaningful level through psychological metaphor.
The videos from Beyond Tellerrand are already online so you can watch the talk now.
In this talk, we’ll discuss how the language we use affects our users and the first steps towards writing accessible, approachable and use case-driven documentation.
While the talk was ostensibly about documentation, I found that it was packed full of good advice for writing well in general.
I had a thought. What if you mashed up these two talks? What if you wrote documentation through the lens of the hero’s journey?
Think about it. When somone arrives at your documentation, they’ve crossed the threshold to the underworld. They are in the cave, facing a dragon. You are their guide, their mentor, their Obi-Wan Kenobi. You can help them conquer their demons and return to the familiar world, changed by their journey.
Wednesday, May 15th, 2019
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.
Monday, April 8th, 2019
200 discarded objects from a dump in San Francisco, meticulously catalogued, researched, and documented by Jenny Odell. The result is something more revealing than most pre-planned time capsule projects …although this project may be somewhat short-lived as it’s hosted on Tumblr.
Wednesday, March 20th, 2019
Ah, what a wonderful treasure trove this is! PDF scans of Apollo era press kits from a range of American companies.
- Official NASA
- Lunar Module
There’s something so fascinating about the mundane details of Isolation/Quarantine Foods for Apollo 11 Astronauts from Stouffer’s.
Monday, January 28th, 2019
Running an experiment for 500 years is hard enough. Then there’s the documentation…
The hard part is ensuring someone will continue doing this on schedule well into the future. The team left a USB stick with instructions, which Möller realizes is far from adequate, given how quickly digital technology becomes obsolete. They also left a hard copy, on paper. “But think about 500-year-old paper,” he says, how it would yellow and crumble. “Should we carve it in stone? Do we have to carve it in a metal plate?” But what if someone who cannot read the writing comes along and decides to take the metal plate as a cool, shiny relic, as tomb raiders once did when looting ancient tombs?
No strategy is likely to be completely foolproof 500 years later. So the team asks that researchers at each 25-year time point copy the instructions so that they remain linguistically and technologically up to date.
Wednesday, March 21st, 2018
Part one of a deep dive by Nathan into structuring design system documentation, published on Ev’s blog.
Tuesday, March 6th, 2018
It’s really heartwarming to see this idea resonating.
Monday, March 5th, 2018
Friday, March 2nd, 2018
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:
- The instructions on the AMP validator page.
- The documentation for Composer, the PHP dependency manager.
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.
Sunday, February 11th, 2018
There’s something quite Bridlesque about these lovely books that Brendan is generating from git commits.
Thursday, January 11th, 2018
Friday, January 5th, 2018
Wednesday, November 8th, 2017
Great advice on writing sensible comments in your code.