Tags: documentation



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.

Principles Apart

I was nervous as hell before my talk at An Event Apart Seattle. I don’t normally get quite so nervous but it was a new talk and also …it’s An Event Apart! They set a very, very high bar.

Once I got on stage though, I just started geeking out. I was talking about design principles, a subject I find fascinating. I’m hoping that some of my enthusiasm for the subject helped make for a compelling presentation.

It was a whirlwind tour, starting with a long-zoom look at design principles in history before moving on to the web, where I took an up-close-and-personal look at CSS and quite a bit of HTML, before pulling back again to talk about our planet, our solar system and our galaxy. Yes, there was a space elevator.

I mentioned a range of people, organisations and projects that have documented their design principles, but rather than fill up the slides with lots of URLs, I gave just one URL at the start (and end) of the talk:


That’s where I gathering today examples of documented design principles. By “documented” I mean “published on the web.” There are some really interesting principles from disciplines like urban design but as long as they are locked up in books that aren’t addressable on the network, I can’t link to them.

This is a fairly small-scale project so I figured a wiki might be overkill but if you know of any good documented design principles that should be added to the list, let me know

Jeremy Keith, Design Principles, Day II, #aea Jeremy Keith, Design Principles, Day II, #aea