Tags: document

79

sparkline

Tuesday, October 9th, 2018

» Baikonur, Earth

A new impressionistic documentary about Space City.

Thursday, August 2nd, 2018

Accessibility: Start with the foundations | susan jean robertson

I encourage you to think about and make sure you are using the right elements at the right time. Sometimes I overthink this, but that’s because it’s that important to me - I want to make sure that the markup I use helps people understand the content, and doesn’t hinder them.

Tuesday, July 31st, 2018

General Magic

A forthcoming documentary about the company spun out of Apple to create a handheld communication device …in 1990.

From mobile computing, social media, downloadable apps and e-commerce to touchscreens, emoji and USB, the products and services that now dominate the tech industry and our day-to-day lives were born at General Magic.

Sunday, June 3rd, 2018

Friday, June 1st, 2018

Document

A little while back, I showed Paul what I was working on with The Gęsiówka Story. I value his opinion and I really like the Bradshaw’s Guide project that he’s been working on. We’re both in complete agreement with Russell Davies’ call for an internet of unmonetisable enthusiasms. Call them side projects if you like, but for me, these are the things that the World Wide Web excels at.

These unomentisable enthusiasms/side projects are what got me hooked on the web in the first place. Fray.com—back when it was a website for personal stories—was what really made the web click for me. I had seen brochure sites, I had seen e-commerce sites, but it was seeing something built purely for the love of it that caused that lightbulb moment for me.

I told Paul about another site I remembered from that time (we’re talking about the mid-to-late nineties here). It was called Private Art. It was the work of one family, the children of Private Art Pranger who served in World War Two and wrote letters from the front. Without any expectations, I did a quick search, and amazingly, the site is still up!

Yes, it’s got tiled background images, and the framesetted content is in a pop-up window, but it works. The site hasn’t been updated for fifteen years but it works perfectly in a web browser today. That’s kind of amazing. We really shouldn’t take the longevity of our materials for granted. Could you imagine trying to open a word processing document from the late nineties on your computer today? You’d have a bad time.

Working on The Gęsiówka Story helped to remind me of some of the things that made me fall in love with the web in the first place. What I wrote about it is equally true of Private Art:

When we talk about documents on the web, we usually use the word “document” as a noun. But working on The Gęsiówka Story, I came to think of the word “document” as a verb.

The World Wide Web is a medium that’s works for quick, short-term lightweight bits of fun and also for long-term, deeper, slower, thoughtful archives of our collective culture.

The web is a many-splendoured thing.

Tuesday, May 15th, 2018

Colour Wheels, Charts, and Tables Through History – The Public Domain Review

These are beautiful!

Featured below is a chronology of various attempts through the last four centuries to visually organise and make sense of colour.

Wednesday, March 21st, 2018

Documenting Components – EightShapes – Medium

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

Tuesday, March 6th, 2018

Monday, March 5th, 2018

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

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:

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.

Tuesday, February 13th, 2018

XML is 20

XML 1.0 was released on February 10th, 1998. I remember the hype around XML at the time—it was our saviour, the chosen one, prophesied to bring balance to data exchange. Things didn’t quite work out that way, but still…

Twenty years later, it seems obvious that the most important thing about XML is that it was the first. The first data format that anyone could pack anything up into, send across the network to anywhere, and unpack on the other end, without asking anyone’s permission or paying for software, or for the receiver to have to pay attention to what the producer thought they’d produced it for or what it meant.

Sunday, February 11th, 2018

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.

Thursday, January 11th, 2018

TNZ Pattern Library Docs

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

Friday, January 5th, 2018

Herman: Automated Pattern Libraries | OddBird

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

Wednesday, December 20th, 2017

The Go-Betweens: Right Here

This looks like a rather good documentary about the best band in the world.

THE GO-BETWEENS: RIGHT HERE

Saturday, December 9th, 2017

Origin story

In an excellent piece called The First Web Apps: 5 Apps That Shaped the Internet as We Know It, Matthew Guay wrote:

The world wide web wasn’t supposed to be this fun. Berners-Lee imagined the internet as a place to collaborate around text, somewhere to share research data and thesis papers.

In his somewhat confused talk at FFConf this year, James Kyle said:

The web was designed to share documents.

Douglas Crockford said

The web was not designed to do any of things it is doing. It was intended to be a simple—even primitive—document retrieval system.

Some rando on Hacker News declared:

Essentially every single aspect of the web is terrible. It was designed as a static document presentation system with hyperlinks.

It appears to be a universally accepted truth. The web was designed for sharing documents, and was never meant for the kind of applications we can build these days.

I don’t think that’s quite right. I think it’s fairer to say that the first use case for the web was document retrieval. And yes, that initial use case certainly influenced the first iteration of HTML. But right from the start, the vision for the web wasn’t constrained by what it was being asked to do at the time. (I mean, if you need an example of vision, Tim Berners-Lee called it the World Wide Web when it was just on one computer!)

The original people working on the web—Tim Berners-Lee, Robert Cailliau, Jean-Francois Groff, etc.—didn’t to try define the edges of what the web would be capable of. Quite the opposite. All of them really wanted a more interactive read-write web where documents could not only be read, but also edited and updated.

As for the idea of having a programming language in browsers (as well as a markup language), Tim Berners-Lee was all for it …as long as it could be truly ubiquitous.

To say that the web was made for sharing documents is like saying that the internet was made for email. It’s true in the sense that it was the most popular use case, but that never defined the limits of the system.

The secret sauce of the internet lies in its flexibility—it’s a deliberately dumb network that doesn’t care about the specifics of what runs on it. This lesson was then passed on to the web—another deliberately simple system designed to be agnostic to use cases.

It’s true that the web of today is very, very different to its initial incarnation. We got CSS; we got JavaScript; HTML has evolved; HTTP has evolved; URLs have …well, cool URIs don’t change, but you get the idea. The web is like the ship of Theseus—so much of it has been changed and added to over time. That doesn’t mean its initial design was flawed—just the opposite. It means that its initial design wasn’t unnecessarily rigid. The simplicity of the early web wasn’t a bug, it was a feature.

The web (like the internet upon which it runs) was designed to be flexible, and to adjust to future use-cases that couldn’t be predicted in advance. The best proof of this flexibility is the fact that we can and do now build rich interactive applications on the World Wide Web. If the web had truly been designed only for documents, that wouldn’t be possible.

Wednesday, November 8th, 2017

The Art of Comments | CSS-Tricks

Great advice on writing sensible comments in your code.

Wednesday, August 23rd, 2017

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!

Friday, July 14th, 2017

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

Thursday, June 1st, 2017

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!