This is a great step-by-step guide to HTML by Estelle.
This is a great step-by-step guide to HTML by Estelle.
I remember Lara telling me a great quote from the Clarity conference a few years back: “A design system needs to be correct before it’s complete.” In other words, it’s better to have one realistic component that’s actually in production than to have a pattern library full of beautiful but unimplemented components. I feel like Robin is getting at much the same point here, but he frames it in terms of correctness and usefulness:
If we want to be correct, okay, let’s have components of everything and an enormous Figma library of stuff we need to maintain. But if we want to be useful to designers who want to get an understanding of the system, let’s be brief.
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.
Always refreshing to see some long-term thinking applied to the web.
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.
An interesting project that will research and document the language used across different design systems to name similar components.
What a lovely way to walk through the design system underpinning the Guardian website.
Bonus points for using the term “tweak points”!
Brian found this scanned copy of a NeXT manual on the Internet Archive. I feel a great fondness for this machine after our CERN project.
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.
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.
Mike’s talk was back-to-back with a talk from Carolyn Stransky called Humanising Your Documentation:
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.
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.
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.
Ah, what a wonderful treasure trove this is! PDF scans of Apollo era press kits from a range of American companies.
There’s something so fascinating about the mundane details of Isolation/Quarantine Foods for Apollo 11 Astronauts from Stouffer’s.
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.
Part one of a deep dive by Nathan into structuring design system documentation, published on Ev’s blog.
It’s really heartwarming to see this idea resonating.
The design system for the Australian government is a work in progress but it looks very impressive. The components are nicely organised and documented.
(I’ve contributed a suggestion for the documentation in line with what I wrote about recently.)
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.
There’s something quite Bridlesque about these lovely books that Brendan is generating from git commits.
New Zealand has a pattern library (in Fractal, no less).