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.
Monday, April 8th, 2019
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.
Wednesday, August 23rd, 2017
Alla looks at ways of documenting animations into a pattern library. I tell ya, her book is going to be unmissable!
Friday, July 14th, 2017
Once again, we can learn from Christoper Alexander’s A Pattern Language when it comes to create digital design systems, especially this part (which reminds me of one of the panes you can view in Fractal’s default interface):
- Each pattern’s documentation is preceded with a list of other patterns that employ the upcoming pattern
- Each pattern’s documentation is followed by a list of other patterns that are required for this pattern
Thursday, June 1st, 2017
Sunday, October 23rd, 2016
A nicely-documented styleguide from Atlassian. It’s not a component library, though—there’s no code here.
Wednesday, August 24th, 2016
An in-depth look at the current Shadow DOM spec. It’s well-written but I don’t think this will really click with me until I start playing around with it for myself.
It’s good to see that the examples have some thought given to fallback content.
There’s also a corresponding tutorial on custom elements
Friday, July 22nd, 2016
Thursday, July 21st, 2016
I think Tyler’s onto something here:
I noticed three qualities that recurred in different combinations. Without at least two, the projects seemed doomed to failure.
I certainly think there’s a difference in how you approach a pattern library intended as a deliverable (something we do a lot of at Clearleft) compared to building a pattern library for an ongoing ever-evolving product.
Thursday, July 14th, 2016
Monday, May 16th, 2016