There's plenty of writing already about why documentation is important. We've all picked up someone else's project or an old code base, looked for the 'getting started' guide and found at best some half baked command line instructions (that probably don't work any more), or at worst nothing at all. Perhaps you've even gone back to one of your own projects, a few months since you last worked on it, and found it in much the same state and you're desperately grepping your history looking for how to start it up.

So why should you write documentation? Well, why shouldn't you? Here are some bad reasons...

"my code is so great, I don't need documentation"

"my unit tests are so great, I don't need documentation"

"my framework of choice is so great, it comes with it's own documentation"

"my framework of choice is so great, it automatically generates documentation for me"

Your code might be great, I don't doubt it. You're a great engineer. But you might not think that in six months time when you've worked on three other projects and can't remember how any of this works any more. Documentation is a great reference guide.

Hey, your unit tests might be pretty swish too, but they probably only tell me how to use your library for simple scenarios, and often only those that were needed to test specific regressions in your library. It probably doesn't help me apply your library to my needs. Documentation is a great tool to help solve problems.

It's nice when frameworks have excellent documentation, but hint, that's documentation for their framework, not for your implementation of it!  Documentation is a great way of developing understanding of your system.

Auto-generated documentation is really just your code transformed into a different format. It doesn't help your audience to really learn how to make the most of your library, and how it can make their project better. Documentation is a great teacher.

This creates four distinct styles of documentation, each with their own purpose:

Guides, how-tos on solving problems with your system

Explanation, helping your audience to build their mental model of your system

Tutorials, teaching ways to make the most of your system

You can read a lot more about these over at documentation.divio.com. It's a great set of principles to follow, and they think so too:

If you can put these principles into practice, it will make your documentation better and your project, product or team more successful - that’s a promise.

With that in mind, that great documentation can serve four distinct purposes, it's now time to turn our attention to how you can create within these areas.

A screen recording is worth a thousand words

Most documentation takes the form of a handful of markdown files in a GitHub repo, perhaps a few pages in your company's Confluence workspace, or maybe you even have a dedicated website to host your documentation. No matter where it lives, most of the time your documentation probably takes the form of written word, typed into a text editor, and hosted online for your audience to read.

But there's more to life than words on a page. Indeed, consider how you might use other formats to share an understanding of your system. You might even find it's easier to create documentation in these other formats, especially if you find writing tedious.

Graphics are probably the most common secondary form of documentation found today. Architecture diagrams, system designs, and networking graphs are found all over the place, and there are lots of excellent tools available to produce them. If you're concerned about your diagrams getting out of date, there are a handful of services looking at how these sort of diagrams can be managed in code, much like you might manage your infrastructure with Terraform, or your database with migrations.

Sometimes showing is easier than explaining it. Grab a couple of colleagues, open up a video call and turn on the screen recorder. Talk through the system, taking them through the areas you're looking to document, encouraging your attendees to ask exploratory questions as you go. You might find a few areas you hadn't considered documenting, or specific features that are hard to explain on the first attempt. Take notes around these and consider if you need to re-record these sections, or develop mental models to help explain them better next time.

You can edit the screen recording down later just to the highlights, or even chunk it up into smaller videos.

Remember: if you're sharing a screen recording, consider adding a transcript and time stamps for key points, to help aid navigation and discoverability.

Some of the best documentation often includes an interactive element, a way for the audience to either play around with your service during the learning process, or a way to check they are developing their understanding as they go. The Apple SwiftUI documentation does this well, with a "Check your understanding" box at the end of each section in their introduction tutorials.

This does a really good job of helping give the audience member the confidence that they've understood what the documentation was telling them, and that they're ready to move on to the next stage. This works especially well in Tutorial-style documentation. Creating advanced interactive behaviour for your tutorials might be time consuming, but there are simple approaches too. GitHub markdown has support for collapsible containers, which can be used to hide answers to questions. You can find more details on how to do this in this Gist.

A handful of additional things to consider

Consider adding a "do not use this if..." section to your documentation, especially if your service isn't well suited for specific scenarios. This can help people understand if it is worth investing their time or whether they should be looking elsewhere.

Get documentation reviewed like any other code contributed to your project, consider the audiences you are targeting too, and make sure it's reviewed by someone from that group. Find time to review it yourself a few weeks after you've completed it, confirming it still makes sense once you've moved on to new things.

If you're hosting your documentation online, consider making it easy to search. Think about what sort of questions your audience might ask, and create ways for them to discover the answers easily. Hosted real-time search tools such as Algolia provide discounted or free search for open source software and non-profits. Make sure you put detailed goals, targets, and outcomes in your documentation, so if you can index it in search, it makes it really easy for your audience to find what they're looking for.

Whilst a bit of a gimmicky name which might not work for all forms of documentation, think about whether you can create the documentation for your new service or API before you build it – a process often referred to as ‘documentation driven development’. You can use that documentation to validate if your idea or API design is sufficient, before then proceeding to write tests and the code itself. More thoughts on this approach can be found in this Gist.

Allow contributions back, if a user finds a mistake, or has a suggestion to improve, give them an easy way to feedback. In-page controls to create GitHub issues, or links to reach out to your team on social media can help a lot.

Tailor your documentation to the individual. Airtable do this really well, creating custom documentation pages for each of your projects within their service. This includes not just the writing, but the code samples and example responses are tailored too.

If you're creating a tutorial, make sure you have a friend or colleague run it through and time it. It often helps to give your audience an idea of how long they'll need to set aside to complete it.

Have you got suggestions on what makes great documentation, or pitfalls to avoid? Drop me a note on Twitter @chrishutchinson, I'd love to hear about your experiences.

Finding your documentation groove

Tips for creating great documentation that your team will love

The launch of iOS 12 brought the release of Shortcuts, a first-party app that allows you to create custom workflows for use by Siri, in the share sheet, and in many other places across iOS.

One feature of Shortcuts is the action “Run JavaScript on Web Page”, which allows you to write any arbitrary JavaScript (based on the feature-set supported by Safari on iOS) and run it on the page. Many of you are likely thinking exactly what I did when I first saw this:

Hey! That’s a bit like a Chrome Extension!

In almost every way, what’s provided by Shortcuts is considerably more rudimentary than a Chrome or Firefox extension, but in this post I’ll run through a few Shortcuts of my own that I’ve written (including links to the code), and hopefully demonstrate how this may just been the beginning of something quite powerful.

Note: This post will include step-by-step guides on creating your own JavaScript-powered Shortcuts. Make sure you’ve downloaded the Shortcuts app for iOS first — link here!

Let’s start simple, you may remember the “Do a barrel roll” easter egg from 2011. We’re going to go ahead an implement this as a Shortcut that you can fire on any web page, directly from the iOS native share sheet.

Don’t want to wait? I’ve already built and uploaded this Shortcut to GitHub, so you can download and use it straight away, here.

To start, we’re going to create a new Shortcut, by tapping the + button in the Shortcuts app. Next, use the search box at the bottom to find “Run JavaScript on Web Page”, and add it to your Shortcut. It’ll bring some sample JavaScript, you’re going to want to replace that with the following lines of code (or grab it from GitHub here) to get that barrel roll goodness.

Hacking with JavaScript and Shortcuts (#1)

This code is pretty straightforward, but if you’re not familiar with JavaScript:

Fill the tag with our barrel-roll 360 degree CSS animation

Add the <style> tag to the page, triggering the animation

Call Shortcut’s completion() method, to tell it our code has finished running

Once you’ve got that code added, tap the settings menu button in the top right, and do the following:

Give your Shortcut a name, try: Do a barrel roll!

Tick the “Show in Share Sheet” option

Open the “Accepted Types” menu, and tap “Deselect All” in the top right

Scroll down, and check “Safari web pages”, and return to settings view

Now your configuration is all set, tap “Done” again to save your Shortcut.

To confirm it works, open Safari, and visit any web page you like. Once the page has loaded, tap the share icon, scroll across to “Shortcuts”, and select your new “Do a barrel roll!” shortcut. Note: the first time you run it, iOS will confirm if you’re happy to run this Shortcut on the website you’ve loaded, you’ll need to confirm. You can see a demo video here.

And there you have it, a pretty simple Shortcut, but one that opens the door for many more possibilities.

Let’s ramp it up a little more, and try to implement a shortcut that activates gyroscope scrolling on any webpage. If your phone is tilted back, it’ll scroll up, start bringing it upright, we’ll scroll down, and bring it up to 90 degrees, and we’ll scroll down even faster.

Hacking with JavaScript and Shortcuts (#2)

Follow the same procedure as before to create a new Shortcut, but paste in the above JavaScript code. This code is a little more complex, but nothing we shouldn’t be able to follow:

Create a function that handles device orientation change

Inside that function, grab the “beta” direction (horizontal tilt) and check the value

Based on the value, do nothing, scroll up, scroll down, or scroll down faster

Assign our function to the deviceorientation event

Call the completion() handler to tell Shortcuts we’re done

This is pretty crude, but will do the trick for now. Make sure you set up the share sheet and Safari Web Page triggers in the Shortcut configuration, save it, and give it a whirl. You should be able to tilt your phone back and forth, and scroll up and down the page!

So this is pretty cool, we can interact with the page, get device details, and make it do stuff! You can see a demo video here.

Hacking with JavaScript and Shortcuts (#3)

Okay, final demo, this time we’re going to write a script that swaps out words for their emoji equivalent. For the purposes of the test, I’ll provide a small object of words and emojis, but there’s no reason you couldn’t bring in a library (just render out a <script> tag to an external URL or use npm and bundle up your Shortcut code using something like Webpack or Parcel).

Create a function to replace all the words with their equivalent emojis in a string

Take the HTML of the page, run it through the function, and set it back again

Call completion() to tell Shortcuts we’re done

Set this up, just as before, and try running it on the Stranger Things Wikipedia page. You can see a demo video here.

Of course, you don’t only have to interact with the web page, you could pull some data from the page (say, the URL or some kind of content identifier), combine it with data from another service (say, an analytics platform), and send it all back to the user via a notification. I did exactly this as a prototype for The Times:

To do this, when you call the completion() method at the end of your JavaScript, just pass some data along with it, like so:

// Your JavaScript logic here
const data = "Data to send back to Shortcuts";
completion(data);

Once back in the Shortcuts app, you can then add additional actions using this data, like “Copy to Clipboard” and “Send Notification”, along with plenty of others.

This post has covered just a few examples I’ve thrown together over the past 24 hours, but highlights some of the possibilities this feature enables. From personal workflows to workplace tasks there are a huge number of potential use cases for this technology. By integrating this with all the other features of Shortcuts, this might just be the start of a whole new way for JavaScript developers to build for mobile devices.

📣 If you’ve done something interesting with JavaScript and Shortcuts, drop me a note on Twitter or GitHub, I’d love to hear more!

Hacking around with JavaScript and Shortcuts in iOS 12

The launch of iOS 12 brought the release of Shortcuts, a first-party app that allows you to create custom workflows for...

One of the tasks of a digital team in any major news organisation is to make the newsroom more efficient. We leverage new technologies in ways that haven’t been done before, and at a pace that’s challenging to keep up with. At The Times and Sunday Times, our team is constantly on the lookout for ways of improving our editorial workflow, and ensuring we get the very best from our great quality journalism.

The digital development team have recently starting looking towards open source (I won’t cover it here, but a Google search will fill you in) as a way of improving our editorial workflow, along with producing better code quicker and contributing back to the community with our own expertise. We recently launched Axis version 1.0, an open source AngularJS charting tool, alongside a number of smaller open source products including WordPress plugins and AngularJS modules. We’ve also forked and modified existing code bases, giving birth to CardKit.

In September 2014, having recently launched Red Box (related reading: see this great Medium article from Callum Jones about Red Box), we wanted an easy way to create and share social cards with our readers. After a rally round the team someone suggested looking at Vox Media’s ‘meme’, an open source social card making tool. A few hours of tinkering later, and we had our own version set up with some simple functionality, along with a new name: CardKit.

With a base version set up, we then spent some time talking to the newsroom, along with our design team, gathering ideas and requirements. Over the next few weeks, we distilled these requirements into a few key features CardKit needed:

Theming — allowing editors and journalists the flexibility to create interesting cards, but within specified design guidelines

Branding — a series of Times and Sunday Times branded elements, including our £1 for 30-days trial offer badge

Control — control over the position of multiple elements on the card

After some development and testing time, we had successfully extended Meme to create a tool we were proud of, which served the needs of our newsroom, and making shareable social cards far more efficient.

Creating a card using CardKit. The process has been sped up for .gif purposes, but seriously — it really is this quick.

Of course, we weren’t finished there. In the process of developing CardKit, we had faced a number of challenges, particularly with the way Meme handled multiple draggable elements, and its use of HTML5 <canvas>. In December, I stumbled into a great library called Snap.svg, a powerful and feature-rich SVG library, which is also open source. After reading the documentation, it became apparent it could become the core of a new CardKit, with increased flexibility and modularity, making it easier for us to achieve our goals, whilst still allowing other users to create the cards they require.

This new version of CardKit (conveniently dubbed CardKit v2), is currently available on GitHub. CardKit v2 implements a simple configuration object, meaning each instance of it can have a different set of editable elements (currently images, text, groups, and shapes). Development is still in its early stages, with a long way to go before it’s ready for use in production. We’ve been able to take some great features from Vox’s Meme project, combine it with our own experience and requirements, to produce something that helps our newsroom do something better, and can feed back into the vibrant open source community the project found its roots in.

We aim for CardKit to become a simple and easy to use tool for everyone to quickly and dynamically create images with rich media. Beyond social sharing cards, we see other uses for CardKit, which have been factored in to its development:

A simple tool for crediting photos — reducing the need to write “(Credit: AP)”, for example, in tweets, saving vital characters

Becoming embeddable, an easy way to create customisable modules for a website that is difficult to extend (think, adding a customised author biography to an article in a WordPress.com theme)

Anything else...! We’ve built it so anyone can run a version of CardKit and set up their own configuration suited to their needs — it’s not tied in to any single output style or layout

We’ll be actively developing CardKit v2 over the next few months, so keep an eye on our GitHub account and Twitter account for further updates.

How we used an open source meme generator to promote our journalism

There’s lot to say about WordPress, some good, some bad. It seems no matter who you talk to, everyone has heard of WordPress, everyone has used WordPress, and everyone has at least one thing they hate about WordPress.

For those I’ve spoken to, that issue can be one of many things. If they’re a developer, it’s ‘The Loop’, or WordPress’ quite frankly awful theming API. If they’re an editor or writer, it’s probably the challenges they face trying to make their work look good, or how they don’t have the flexibility to try new things.

Over the past few years I’ve spent a lot of time working with WordPress. I started by building a news site for my old student newspaper, Redbrick(2011–12). I then worked at a WordPress development agency, building anything from small personal blogs, to large ecommerce websites.

More recently, I’ve tried using it in a entirely new way. In a nutshell, this new stack consists of:

ACF to WP-API (an open source plugin I’ve written to include Advanced Custom Fields data in the WordPress API)

I’ve used this set of tools a few times to rapidly (and I mean really rapidly) produce a structured and fully-featured CMS backend, with flexibility and extensibility based on the needs of the project (Advanced Custom Fields & ACF to WP-API). By using the REST API provided by WP-API, I’ve been able to forget about some of the weaker aspects of WordPress and take advantage of some of its better features — such as revisions, a simple editing interface, and familiarity.

I can then use any frontend framework, such as AngularJS, to consume the REST API, and display the content in the form I choose, taking advantage of the great features of those JavaScript frameworks, without the hassle of WordPress theming. These frameworks make it easy to swap out the API at a later point to a newer or alternative CMS, whilst maintaining the same frontend code base.

I’ve found this stack exceptionally useful during hack days for rapidly producing a flexible CMS, spending less time worrying about models, databases and editing interfaces, and more time focussing on the core idea (the frontend product). Advanced Custom Fields allows me to add and create the fields I need for the specific project, whilst maintaining an easy to use interface. I competed on a staff team at The Times & The Sunday Times’ Build The News in October 2014 and our team built Placard (a flexible and easy to use campaigning platform) based on this stack — both the WordPress plugin & AngularJS frontend are available on GitHub.

Whilst this combination of tools does not solve all the problems WordPress has, it allows both users and developers to take advantage of it as a powerful CMS, and pair it with their frontend framework of choice. In separating the data layer from the presentation layer, adding new features and extending functionality becomes quick, and very easy.

Are you using the WordPress API for anything? Let me know on Twitter @chrishutchinson.

My WordPress Renaissance

There’s lot to say about WordPress, some good, some bad. It seems no matter who you talk to, everyone has...

Journal 2021

Finding your documentation groove

2018

Hacking around with JavaScript and Shortcuts in iOS 12

2015

How we used an open source meme generator to promote our journalism

My WordPress Renaissance

Chris Hutchinson