Journal tags: github

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 Tippy.js, a lightweight JavaScript library.
• 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.

I like sparklines a lot. Tufte describes a sparkline as:

…a small intense, simple, word-sized graphic with typographic resolution.

Four years ago, I added sparklines to Huffduffer using Google’s chart API. That API comes in two flavours: a JavaScript API for client-side creation of graphs, and image charts for server-side rendering of charts as PNGs.

The image API is really useful: there’s no reliance on JavaScript, it works in every browser capable of displaying images, and it’s really flexible and customisable. Therefore it is, of course, being deprecated.

The death warrant for Google image charts sets the execution date for 2015. Time to start looking for an alternative.

I couldn’t find a direct equivalent to the functionality that Google provides i.e. generating the images dynamically on the server. There are, however, plenty of client-side alternatives, many of them using canvas.

Most of the implementations I found were a little heavy-handed for my taste: they either required jQuery or Processing or both. I just wanted a quick little script for generating sparklines from a dataset of numbers. So I wrote my own.

I’ve put my code up on Github as Canvas Sparkline.

Here’s the JavaScript. You create a canvas element with the dimensions you want for the sparkline, then pass the ID of that element (along with your dataset) into the sparkline function:

sparkline ('canvasID', [12, 18, 13, 12, 11, 15, 17, 20, 15, 12, 8, 7, 9, 11], true);

(that final Boolean value at the end just indicates whether you want a red dot at the end of the sparkline).

The script takes care of normalising the values, so it doesn’t matter how many numbers are in the dataset or whether the range of the numbers is in the tens, hundreds, thousands, or hundreds of thousands.

There’s plenty of room for improvement:

• The colour of the sparkline is hardcoded (50% transparent black) but it could be passed in as a value.
• All the values should probably be passed in as an array of options rather than individual parameters.

Feel free to fork, adapt, and improve.

The sparklines are working quite nicely, but I can’t help but feel that this isn’t the right tool for the job. Ideally, I’d like to keep using a server-side solution like Google’s image charts. But if I am going to use a client-side solution, I’m not sure that canvas is the right element. This should really be SVG: canvas is great for dynamic images and animations that need to update quite quickly, but sparklines are generally pretty static. If anyone fancies making a lightweight SVG solution for sparklines, that would be lovely.

In the meantime, you can see Canvas Sparkline in action on the member profiles at The Session, like here, here, here, or here.

Update: Ask and thou shalt receive. Check out this fantastic lightweight SVG solution from Stuart—bloody brilliant!

I’m on a workshopping roll. Fresh from running my Responsive Enhancement workshop in Belfast, I’m now heading to Düsseldorf for Beyond Tellerand where I’ll be running the workshop on Sunday (and if you can’t make it, don’t forget that you can book the workshop for your own workplace too).

As part of the process of building a responsive site from the content out rather than the canvas in, I talk about beginning with the individual components divorced from any layout context. Or, as Mark puts it, “start with the bits.”

That’s the way I’ve been starting most of my projects lately: beginning with the atomic units of content and styling them first before even thinking about layout. This ensures that those styles are extremely robust—because they don’t depend on any particular context, they can be safely dropped into any part of a page.

I’ve been calling this initial collection of markup snippets a pattern primer. To help create the pattern primer, I’ve written a little bit of PHP to automatically generate a page of patterns from a folder of HTML snippets.

In my workshop I keep promising to put that script on Github. I finally got around to doing that and you can find it at github.com/adactio/Pattern-Primer.

Take a look at an example pattern primer to get an idea of what a handy deliverable this can be if you’re handing off to other developers. It also acts like a page of unit tests for CSS—whenever you’ve been messing around in the stylesheet you can refresh the page to quickly check to see if anything looks screwed up.

Grab the code; improve upon it; share your changes.

I’m continually struck by a sense of web design deja vu these days. After many years of pretty dull stagnation, things are moving at a fast clip once again. It reminds of the web standards years at the beginning of the century—and not just because HTML5 Doctor has revived Dan’s excellent Simplequiz format.

Back then, there was a great spirit of experimentation with CSS. Inevitably the experimentation started on personal sites—blogs and portfolios—but before long that spirit found its way into the mainstream with big relaunches like ESPN, Wired, Fast Company and so on. Now I’m seeing the same transition happening with responsive web design and, funnily enough, I’m seeing lots of the same questions popping up:

• How do we convince the client?
• How do we deal with ad providers?
• How will the CMS cope with this new approach?

Those are tricky questions but I’m confident that they can be answered. The reason I feel so confident is that there are such smart people working on this new frontier.

Just as we once gratefully received techniques like Dave’s CSS sprites and Doug’s sliding doors, now we have new problems to solve in fiendishly clever ways. The difference is that we now have Github.

Here’s a case in point: responsive images. Scaling images is all well and good but beyond a certain point it becomes overkill. How do we ensure that we’re serving up appropriately-sized images to various screen widths?

Scott kicked things off with his original code, a clever mixture of JavaScript, cookies, .htaccess rules and the -data HTML5 attribute prefix. Crucially, this technique is using progressive enhancement: the smaller image is the default; the larger image only gets swapped in when the screen width is wide enough. Update: and Scott has just updated the code to remove the -data-fullsrc usage.

Mark was able to take Scott’s code and fork it to come up with his own variation which uses less JavaScript.

Andy added his own twist on the technique by coming up with a slightly different solution: instead of looking at the width of the screen, take a look a look at the width of the element that contains the image. Basically, if you’re using percentages to scale your images anyway, you can compare the offsetWidth of the image to the declared width of the image and if it’s larger, swap in a larger image. He has written up this technique and you can see it in action on the holding page for this September’s Brighton Digital Festival.

I particularly like Andy’s Content First approach. The result is that sometimes a large screen width might mean you actually want smaller images (because the images will appear within grid columns) whereas a smaller screen, like maybe a tablet, might get the larger images (if the content is linearised, for example). So it isn’t the width of the viewport that matters; it’s the context within which the image is appearing.

All three approaches are equally valuable. The technique you choose will depend on your own content and the specific kind of problem you are trying to solve.

The Mobile Safari orientation and scale bug is another good example of a crunchy problem that smart people like Shi Chuan and Mathias Bynens can tackle using the interplay of blogs, Github and to a lesser extent, Twitter. I just love seeing the interplay of ideas that cross-pollinate between these clever-clogged geeks.