Tags: documentation

45

sparkline

The Guardian digital design style guide

What a lovely way to walk through the design system underpinning the Guardian website.

Bonus points for using the term “tweak points”!

NeXT Software and Peripherals catalog Fall 1989

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.

How to run a small social network site for your friends

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.

Humanizing Your Documentation - Full Talk - Speaker Deck

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.

The Bureau of Suspended Objects

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.

Apollo Presskit Directory

Ah, what a wonderful treasure trove this is! PDF scans of Apollo era press kits from a range of American companies.

Categories include:

  • Official NASA
  • Earth
  • Launch
  • Lunar Module
  • Moon
  • Astronauts
  • Reveal

There’s something so fascinating about the mundane details of Isolation/Quarantine Foods for Apollo 11 Astronauts from Stouffer’s.

The 500-Year-Long Science Experiment - The Atlantic

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.

Documenting Components – EightShapes – Medium

Part one of a deep dive by Nathan into structuring design system documentation, published on Ev’s blog.

Australian Government Open Language for Design

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.)

Brendan Dawes - Using a Git Repo to create a physical document of the work

There’s something quite Bridlesque about these lovely books that Brendan is generating from git commits.

TNZ Pattern Library Docs

New Zealand has a pattern library (in Fractal, no less).

Herman: Automated Pattern Libraries | OddBird

A lightweight style guide generator. This one uses SassDoc to parse out the documentation for colours, type, etc.

The Art of Comments | CSS-Tricks

Great advice on writing sensible comments in your code.

Integrating Animation into a Design System · An A List Apart Article

Alla looks at ways of documenting animations into a pattern library. I tell ya, her book is going to be unmissable!

A Design System Grammar | Daniel T. Eden, Designer

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

Lost My Name Design System

The really nicely documented design system for Lost My Name.

They’ve also written up the process of creating the design system which includes a refreshingly honest account of missteps made along the way—very valuable!

Overview | Atlassian Design Guidelines

A nicely-documented styleguide from Atlassian. It’s not a component library, though—there’s no code here.

Shadow DOM v1: self-contained web components | Web Fundamentals - Google Developers

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

Fractal Documentation

This is the tool that we use at Clearleft to generate pattern libraries. It’s pretty damn cool. Mark built it. It’s pretty damn cool.