Recommended open source docs

Programming books and documentation on shelfHaving written a fair bit of technical documentation, this tweet requesting recommendations for the best open source docs caught my eye:

Thankfully lots of people were keen to suggest good examples and six hours later I went through the replies. The variety was surprising, from man pages to tutorials to core modules so well written you “don’t really need documentation to understand it”! In the end, there were a few that got several mentions so for the record, here are the open source docs that were recommended at least twice, with one clear winner:

Photo by Niels Heidenreich:

How to eat crêpes (pancakes) by a real French person

Close up of a delicious-looking crêpe (pancake).Being British I’m naturally a connoisseur of fine cuisine but I’ve never mastered pancake-folding, crêpe-rolling, whatever you like to call it — until now. My friend and genuine femme française Coralie developed the perfect pancake preparation process but alas, it’s only in French! Perhaps it’s a government conspiracy to preserve tradition. Perhaps she enjoys the sight of Englishmen dribbling melted ice-cream down their shirts. In any case the secret’s out. This is what she has to say…

The technique

  1. Spread your favourite mixture on your crêpe. Me, I usually spread a layer of Nutella and sprinkle a small amount of caster sugar (to make it crispy).
  2. Take one edge and fold over one third of the crêpe. Take the opposite edge of the crêpe and fold it over by the same amount so that you have an oblong that is the length of the crêpe and one third the width.
  3. Roll the crêpe in the direction of the length.
  4. Munch like a spring roll.


  • A better grip. You only need one hand to hold it.
  • No leakage. Your mixture is secure in your watertight crêpe.
  • The cross-section is very pretty to look at. (There are those for whom this matters.)
  • Time saving. Rolling time is slightly better than with classic rolling or folding. On the other hand, eating time will unquestionably be faster, which enables you to scoff a greater quantity of crêpes.

Et voila. According to Coralie there are no disadvantages. But really, Nutella AND sugar?!

Photo by Paul Downey:

Online security basics: Clicking & downloading

Screenshot of Security Now video episodeNow our child is using computers and the web more and more, I’ve been thinking a lot about protecting children on the internet. There seems to be an endless list of things you should and shouldn’t do but I was struck by some simple advice in the latest Security Now episode (#507) that provides a lot of protection to start you off.

Regarding clicking links in emails, from 1:39:10 in the show Steve Gibson makes the distinction between mails that you’re expecting and mails that you’re not. In other words:

Don’t click links in emails that you weren’t expecting.

For example…

  • Probably safe: You register on a website and then get a confirmation email from them.
  • Probably safe: Your dad is looking to buy a motorbike and sends you a link to one on eBay.
  • Possible evil trap: An email from PayPal asks you to verify your details. To stay safe, you should go to PayPal’s site directly without clicking the email link.

Steve then goes on to mention another security expert, Brian Krebs, with this piece of advice:

Don’t download something you didn’t go looking for.

Super-sensible advice that actually works offline as well, for example in not signing up to financial offers and deals that you weren’t previously considering. Brian also has more basic rules for online safety that I recommend.

So there you go kids, follow these two rules and you’ll save yourself — and your nervous parents — a lot of trouble:

  1. Don’t click links in emails that you weren’t expecting.
  2. Don’t download something you didn’t go looking for.

Song: Oh! Selector ♪


Get high quality versions of this song from iTunes and Bandcamp.
Also, free not-quite-so-high quality downloads are available from SoundCloud and


Now when I was a young boy startin' out in this industry
I remember this pearl of wisdom that the internet gave to me.
To manipulate or decorate something on a web page
First ya gotta grab it and there's pretty much just one way...

Oh selector, oh won't you fetch for me
With your magic sense, all the elements within the old DOM tree.

Now selectors can be used in CSS, oh but there's more.
In plain ol' JavaScript as well with querySelector().
And don't forget the libraries like jQuery and so
You could say that they're essential if you wanna be a pro.


The next step on your journey is to learn selector syntax.
There's not much to remember so don't worry, just relax.
You start with a plain ol' tag name if you want it to be styled,
Use "plus" for adjacent sibling and "greater than" for a child.


A dot is for a class name and for IDs it's a hash.
Use square brackets for attributes and you're sure to find a match.
Now :hover needs a colon like :focus and :target.
There's other stuff as well but that's enough to get you started.


One final word of warning for my song to be complete.
Remember please that all IDs have got to be unique.
They're bad 'n' they're mean and they don't fight clean and you're gonna find it tough
If you use more than one of each because this DOM ain't big enough.

[Chorus x 2]

Tech event planning checklist

Someone speaking at a tech eventThis is mostly a reminder for myself when planning future tech events (meetups, hackathons, etc.) but others might find it useful too. Just print it out and cross off the bits that aren’t relevant. It’s based on my experience as an organiser, speaker and attendee but if I’ve forgotten something please leave a comment.

Early planning

Name and topic
Consider a hashtag when you choose the name, and of course make sure there’s interest in the topic first!
Speaker list
You can get provisional buy-in from one or two speakers and use that to attract others. Speakers always want to know who else is in the line-up.
Date & time
The hardest part. Accept that you’ll never find a perfect date. Work with the locations available to you and check the calendar for other similar events.
Diversity/fairness policy
After a few controversies, more events are making clear their diversity policy and attracting a better variety of speakers and audience. Here is a sample diversity statement and sample code of conduct, both available under a Creative Commons license.
Choose when deciding on dates. Visit in person in advance.
Lucky you! Plan for unexpected expenses.
Allow ten minutes at the end for questions, a summary or just a buffer in case of overruns. Also include a break for events longer than two hours.
Takes time. Be ready to tell the sponsors the event details, what you need the funds for and how they will benefit. Your life will be easier if you can manage without sponsorship.


Main blog post/event page
Good idea to create a shortlink (e.g. with Bitly for easy sharing).
Map & transport
Date, time & duration
Free will save you a whole lot of hassle. Even so, make it clear whether people need to register or not.
Target audience
And the benefit of attending.
Perhaps incorporate it into the event name.
Contact details for more info
Whether they’ll be a video or live streaming


Volunteers & helpers
Make clear that their help is voluntary but be sure to show your appreciation. Reserve some snacks or swag for them if you can.
Chairs for everyone
Make sure you reserve some for the speakers near the front.
John Allsopp (Web Directions) says good coffee is a must.
Signs for the event and the bathrooms
Make the text big. Here’s a bathroom image you can freely use.
Somebody to welcome and help the speakers.
Inform security/building reception
Keep them happy and in-the-know.
Lanyards or stickers
Or stay anonymous.
Power supplies
Lots! If it’s difficult to spread them around the room, have a charging table or two at the back.
Goes without saying. Make sure it’s more reliable than you think you’ll need.
Projector & screen
Don’t forget where the speaker will stand and a power socket for them.
Mics & audio
Clip-on mics are best but require a bit of setup time. If possible, also have a hand mic for audience questions.
Decide in advance if you’re going to be strict or if you’ll give the speakers a few minutes leeway. In any case, someone needs to be ready to stop them if they get carried away.
Water for speakers
Sponsor logos
Be ready to show them on screen before/after the event and during breaks. You may also need a table for sponsor stickers and goodies.
Have marker pens, paper, scissors and duct tape ready. Any event, always.

Speaker communication

Length of session
Also whether they need to leave time for questions.
Target audience and size
Adaptor reminder
Power & internet availability
Remind them to have an offline version of their slides and demos.
Costs you’ll cover, if any
Photo/video permission
Only if you’re planning this

Start of event

Welcome & thank you (speakers, helpers, sponsors, host and attendees)
Wifi access point and password.
Have this on a sign as well. Don’t forget the hashtag or IRC channel.
Photo policy
Let people know if they can’t take photos. Check people are OK with you publishing event photos.
Bathroom location
Emergency exits
Smoking area

During the event

Check Twitter
Gauge the atmosphere and be ready to ask the speakers to speak louder, slower, etc.
Walk around the room (discretely)
Do people look too hot or cold? Can the people at the back see and hear?
Take photos
Think of your post-event blog post.
Repeat questions
Always make sure the speaker repeats any questions from the audience to ensure that everyone can hear.

At the end the event

Thank you (speakers, helpers, sponsors, host and attendees)
Further info
Tell people where to go for slide links, next event details, etc.
Tidy up
Ask the helpers to stay a bit longer to get it done.
Take down the signs
Don’t forget any outside.
Get feedback, either informally or by using a questionnaire.
Share out leftover snacks
Give your hard-working helpers priority.

After the event

Publish photos
Ideally have a blog post with a brief report and thank you note.
Slide links
Try to ask speakers at the event or by mail afterwards to add to the event page.
Spread the word
Continue making a buzz to get people eager for your next event!

Screen readers 1, humans 0

Spoken version: MP3 | OGG

Yesterday I sent out a one-question survey on Twitter about screen readers. I’d had this fantastic idea for a website plugin that would enable blog editors to easily record an audio version of their blog posts when publishing [1]. Vision-impaired users would rejoice, website traffic would shoot up and I’d be rich and famous. To double-check, I asked the following question which was retweeted and replied to by several kind souls:

I expected replies along the lines of “stupid question, of course a human recording is better but we have no choice”. How wrong I was.

If you’re not sure how a blind or low-vision user can “read” a webpage, listen to the following short video showing a screen reader in action.

When I’ve seen friends use screen readers it’s always struck me as sounding difficult to understand and likely to get annoying after a while. Where’s the warmth or personality in that mechanical voice?! But I was enlightened as to how incredibly empowering this technology is and the replies I got were pretty unanimous — screen readers win hands down.

Benefits of screen readers

  • Ability to control such as jumping forwards, backwards or elsewhere in the page
  • Ability to check spelling
  • Ability to listen by word
  • Ability to change reading speed (humans are too slow)
  • Ability to follow links

Some of these are also possible with JavaScript, e.g. changing the speed of an audio file, but it would add an extra UI to the interface that the user is already familiar with. I suppose it’s similar to my beloved Kindle — I now feel the limits of books printed on paper compared to ebooks with their dictionary lookups, highlighting, linking, etc.

The only non-unanimous opinion was for fiction where a human narration is sometimes preferred for continuous reading and to feel emotion.

So another day older, another day wiser and thanks to everyone who sent comments.


  1. When editing a blog post, it should be possible to use getUserMedia to record the audio, send that to the Web Audio API and export it as a WAV file using the Recorder.js library. Then get the WAV file transcoded to OGG or MP3 via an online API such as (no affiliation) and uploaded to cloud storage. The resulting URL could be inserted into an audio element at the top of the blog post, a bit like this one.

Responsive is not just visual: Three useful web APIs

A mobile user using a laptop outside.Mobile users are on the go. They’re rushing to get a train or busy meeting people. They don’t have much time and they’re on a slow connection. Right?

The answer of course is not necessarily. So-called mobile browsing could include shopping online while tucked up in bed, sending messages while watching TV or giggling at silly photos while relaxing in a cafe. It could also include being out and about but not using a mobile device.

In reality we have no idea what the users of our website are doing or where they are, and it would be a huge invasion of privacy if we did! Our fancy responsive designs should therefore not only look good but also be flexible enough to handle a variety of situations.

In other words, responsive doesn’t mean responding to screen size or even device capabilities. It means responding to the user’s environment (as much as possible).

But enough chatter. How can we do this in practice?

There are three handy web technologies that take us part of the way there: the Battery Status API, the Network Information API and Ambient Light Events. Support for all of them is mostly Chrome and Firefox for now, but keep an eye on and for the latest support info. And now, on to the APIs…

Battery Status API

Why use it

Knowing whether your user is plugged in or not and whether their battery has much juice left can influence how your site reacts. Battery-draining features such as repeated actions and animations can be reduced or disabled, for example. Or you could notify the user and offer to save the current state in case there’s a sudden shutdown.

How to use it

The spec had a rewrite recently and now uses shiny new promises. The advantage of this is that the API is asynchronous, meaning that when you call the getBattery() method the browser makes sure the BatteryManager object is ready before you try to read its attributes. Those attributes are:

  • charging (a boolean)
  • chargingTime (in minutes)
  • dischargingTime (in minutes)
  • level (a number between 0 and 1)

Each of these attributes has an event so you can listen for when they change. In practice, you could use the attributes and events like this:

// Prepare a function to display the battery status
function showStatus(battery) {
  battery.onchargingchange = function () {
    console.log('Charging: ' + battery.charging);
  battery.onchargingtimechange = function () {
    console.log('Charging time remaining (mins): ' + battery.chargingTime);
  battery.ondischargingtimechange = function () {
    console.log('Discharging time remaining (mins): ' + battery.dischargingTime);
  battery.onlevelchange = function () {
    console.log('Battery level: ' + battery.level);

// Check for browser support first
if (!!navigator.getBattery) { // The latest API is supported
  // Use the battery promise to asynchronously call showStatus()
  navigator.getBattery().then(function(battery) {
} else if (!!navigator.battery) { // The old API is supported
  var battery = navigator.battery;

Guille Paz has made a nice battery status demo which includes code for the old and new versions of the spec.


This API has the best support of the three with Opera, Chrome and Firefox having implemented it. In the case of Firefox, the implementation currently uses an old version of the spec so for the time being it’s best to allow for both versions in your code.

Network Information API

Why use it

You’re probably aware of the navigator.onLine HTML5 attribute and its wide browser support but that only tells us if the user is connected to a network or not. For more detailed information about the network we need the aptly-named Network Information API. With the data it provides you could opt to show smaller or lower-quality images to users on slow connections, or only show a video background when you know the network speed is fast. Be careful when making assumptions though — wifi doesn’t necessarily mean fast.

How to use it

When fully implemented this provides the type and speed of connection using two attributes (type and downlinkMax) on the global navigator object. Let’s jump straight into an example…

// Some browsers use prefixes so let's cope with them first
var connection = navigator.connection || navigator.mozConnection || navigator.webkitConnection;

// Check for browser support
if (!!connection) {
  // Get the connection type
  var type = connection.type;

  // Get the connection speed in megabits per second (Mbps)
  var speed = connection.downlinkMax || connection.bandwidth;

So easy! The type values are a pre-defined selection of self-explanatory strings:

  • bluetooth
  • cellular
  • ethernet
  • none
  • wifi
  • wimax
  • other
  • unknown

Network speed, when available, is exposed as downlinkMax, previously called bandwidth, although in reality this is difficult for browsers to measure so it may be a while before we’re able to use it. You can also attach a change event listener to navigator.connection to be even more responsive.

For a more thorough look at this API and its background, Aurelio De Rosa has written a good tutorial and network information demo which I recommend.


In the browsers I tested only connection.type was supported properly and that was only in Chrome for Android and Firefox Mobile/OS (you may need to ensure dom.netinfo.enabled is set to true). It’s still early days for this API but its simplicity means it could easily be incorporated into your website or app.

Note: There is a version of the spec hosted on that currently says work on it has been discontinued. This refers to an older version and current work is being done in the GitHub-hosted version, which should eventually migrate to the W3C site.

Ambient Light Events

Why use it

We’re probably all familiar with struggling to read a screen in bright sunlight. Increasing the contrast of what’s displayed on the screen or hiding distracting backgrounds can make content much easier to read in such cases. The opposite is true — reducing how vivid a design is can avoid users screaming and covering their eyes when in a dark environment.

How to use it

Tomomi Imura, AKA @girliemac, has the definitive lowdown on how to respond to differing levels of light. Eventually we’ll all be able to use CSS4 media queries so when the light-level is dim, for example, we can respond accordingly. In the meantime though, there’s the more precise JavaScript approach which gives you access to data from the device’s light sensor. You just listen for a devicelight event and use that event’s value attribute to get the brightness of the user’s surroundings measured in lux. For example:

window.addEventListener('devicelight', function(e) {
  var lux = e.value;

  if (lux < 50) {
    // ambient light is dim so show lower-contrast version

See Tomomi's article for a more detailed example with added CSS and a link to her ambient light demo on CodePen.


At the time of writing support is only available in Firefox and Chrome beta for Android but here's a short video of her code in action:

Of course, these are not the only web technologies that are part of responsive web design but if you want to show the world that you know more than just media queries, they're a good place to start.

Please Retweet This Song ♪


Get high quality versions of this song from Bandcamp.
Also, free not-quite-so-high quality downloads are available from SoundCloud and


I wrote a new song and put it up on the web.
When I checked the next day, the number of plays, to my dismay was ten.
Maybe my music is not that great in the end.
Maybe I should sell myself to my friends.

And if you think this is true
There's one thing you can do

Please retweet this song
That's all they seem to say
Please retweet this song
Is the mantra of today
And if you agree
If you see the irony then
Please retweet this song

So many people are desperate to be heard.
They try to promote something they wrote to get upvotes on their network.
They urge us to click, to share and subscribe.
No need for humility, they wannabe a celebrity online.

And if you share this point of view
What I'd really like you to do is

Please retweet this song
That's all they seem to say
Please retweet this song
Is the mantra of today
And if you agree
If you see the irony then
Please retweet this song

Maybe this is not a new thing
The spread of personal marketing
People have always used their peers 
To cultivate and propagate and advocate and disseminate and circulate their ideas

Please retweet this song
That's all they seem to say
Please retweet this song
Is the mantra of today
And if you agree
If you see the irony then
Please retweet this song

And as they keep sending metweets galore
The rest of us will endeavour not to measure our friends with a score
And as they grow ever greedier
My proposal is to focus on the social in social media.

And if you feel like this too
I think you know by now what to do

Please retweet this song
That's all they seem to say
Please retweet this song
Is the mantra of today
And if you agree
If you see the irony then
Please retweet this ...

Please retweet this song
That's all they seem to say
Please retweet this song
Is the mantra of today
And if you agree
If you see the irony then
Please retweet this, don't delete this, just retweet this song

Released under a Creative Commons (attribution, non-commercial) license.

Song: Step Away From The Screen ♪

A lullaby for geeks (well, mostly for myself).


Get high quality versions of this song from iTunes and Bandcamp.
Also, free not-quite-so-high quality downloads are available from SoundCloud and


Darkness is here and the streetlamps are lit.
But you're still awake reading comments on the 'net.
You're not in bed yet.
So someone was wrong on the internet today.
They can wait till tomorrow to hear what you've got to say.
Step away from the screen,
Away from the screen and take a break. (Take a break)

Your face is filled with a soft flourescent glow.
You smile as you watch one more funny video.
Kittens in the snow.
Now give your brain a rest and step back.
The people around you have all hit the sack.
Step away from the screen,
Away from the screen and relax. (And relax)

A million pixels reflect in your eyes.
You say you're not tired, well it's hardly a surprise.
So mesmerized.
But bookmark the sites you wanna keep.
Resist the temptation to send one more tweet.
Step away from the screen,
Away from the screen and go to sleep. (Go to sleep)

Step away from the screen,
Away from the screen and go to sleep. (Go to sleep)

Released under a Creative Commons (attribution, non-commercial) license.

Song: Waiting to Load ♪

A short song about the frustrations of slow websites, especially on mobile.

Go to the song’s SoundCloud page to download, leave a comment, etc.


My heart is pounding as I step off the train
So excited to finally see you again.
I forgot the address of our meeting place tonight
So I get out my phone and check the website.

But there's nothing on the screen, nothing at all
No words appear as I scroll
I picture you sitting alone
As I wait for this website to load
Tired and frustrated
Scared I won't make it
And still this website won't load


The icon in the cover image is from the wonderful