A couple of weeks ago I moved into a new role at Made Tech, looking across a wider range of products and projects at Hackney Council. This has inevitably come with an influx of new people to meet and new things to get my head around. I picked up a Remarkable 2, on the advice of my predecessor (really I've wanted one for months, they just helped tip me over the edge 😅), to help me structure my notes, maintain a better record of the discussions I'm having, and to keep myself honest about completing the things I've promised to do. So far I'm firmly in the position of taking lots of notes but I'm still not at a place where I'm able to digest them and act on them. Improving this is a goal of mine for the next few weeks.

I got a direct message on Twitter last week about my Train Departure Screen Raspberry Pi project; the message was asking for help in understanding the code I'd written to power the screen. I had intended to reply with a brief overview of how the code works, the main entry points and primary processes / methods, but I felt it might be more useful if I pulled that out of a direct message and instead published a full write up for others to enjoy and learn from too.

I have started doing this and hope to publish something soon, although I was stopped in my tracks by a totally coincidental discussion that happened at work about explaining the behaviour of a system or application. The discussion largely centred around the difference between explaining the codebase (aka. the codebase is the application) versus explaining the abstract capabilities of the application (of which the codebase is just one representation of those capabilities).

The discussion highlighted a few interesting concepts and tools, notably the concept of 'Moldable Development' via Glamorous Toolkit and Projectional Editing, a way of understanding and editing a system through more contextually-relevant projections. While I suspect I will finish writing up the application in a more traditional way (focussing on the codebase itself), given the fairly simple nature of the system it has presented a good opportunity to think about alternative ways of explaining it and whether these concepts could help me publish something that would be useful for different audiences. I hope to dive into in this further the coming weeks.

Weeknotes for week beginning 12th July 2021

I’ve been using Slack for a long time. A really long time – seven years in fact. Since then Slack has evolved into the super-powered chat app we all know today.

In that time I've run a handful of teams and have helped each of them to make the most of Slack, turning those “I don’t have time to check Slack”-ers into “I don’t know how I could work without Slack”-ers. In each case it came down to being clearer and more transparent about where messages should go, and where you can find them later.

Here are my tips to help you do the same for your team or organisation.

There’s an phrase I often think about that embodies how I think about Slack channels:

A place for everything and everything in its place.

In essence, in the context of Slack, meaning there should be an obvious home for each message, file or document you share, and it should be easy to find them later. Both creation and discovery should be simple for everyone in your organisation.

In order for this to work, it’s fundamental that the right channels exist, their purposes are clear, they are renamed when their working context changes, archived when no longer needed, and unarchived (not recreated!) if you ever need them again.

Avoid mysterious channel names like #project-gravy-train or #new-experience-swt. Think about someone new joining your organisation. Channel names should be self explanatory, and avoid acronyms unless absolutely necessary. Better examples would be #iphone-app-rebuild or #smart-water-technology-user-testing. This makes it easier for your colleagues to discover channels (through the channel list, or using the cmd/ctrl + K shortcut) and more obvious from the name what each channel's purpose is. Note: Slack increased the channel name character limit in 2019, so don’t be afraid of longer channel names!

Naming related channels with a consistent prefix can help discovery too. For example, your finance team might have:

#finance-support: for colleagues who need support on finance issues

#finance-operations: for the finance team to use internally for their own day-to-day operations

#finance-workshop-july-21: a temporary channel for the finance and people teams to organise their upcoming three day workshop

When a project or team’s remit changes, consider renaming your channels to accommodate. For example, if you previously had a team responsible for the customer subscription journey (#subscriptions-team), and now they also look after profile management, you might rename that channel to #subscriptions-and-profiles-team. Something to consider: If you have a full team reorganisation, decide if you want to rename old channels (in order to keep the channel history in place) or archive them and start fresh. Remember, you can always get back to archived channels and their content using search, the channel list, or the cmd/ctrl + K shortcut.

Note: by default, not all Slack workspaces allow channel renaming without admin permissions. Ask your Slack owners about enabling this if it isn't already.

With all these channels, I wouldn’t blame you for thinking “how are me and my team keep on top of all this?!”. Below the user groups and welcome messages sections have some extra suggestions for helping with this.

In most teams it’s natural to have leavers and joiners over the course of their life. Slack can help making that process as smooth as possible for new and existing members of the team, as well as for your stakeholders, through user groups.

You might have found yourself in this situation, stakeholders and senior members of staff know one or two of the highest profile members of a given team. When there’s an issue or the stakeholder has a question or feature request, they send a direct message to those people, entirely skipping the team channel, or they do use the channel but they just tag a single person. This can be frustrating for visibility or alleviating the pressures created by single points of communication. 

This is where user groups come in. You can create teams of Slack users with their very own @ handle. For example, the team that work on your payroll might be the @payroll-team. This means you can easily reach the Payroll team, without having to know who is in the team, or who is on holiday.

But user groups have another powerful feature, default channels. With these, you can set a user group to have a set of channels which every member of the group is automatically added to. Using the finance example from earlier, having a @finance-team user group with a default channel of #finance-operations makes onboarding new team members to Slack a breeze. If anyone wants to see who makes up the current Finance team, they can check the team membership and their profiles too – easy!

If you want to give it a go, you can follow this Slack guide for setting up a user group.

Note: the creation and management of user groups may be disabled in your Slack workspace. Speak to your Slack admins to get this enabled.

The final piece of the channel discovery puzzle is welcome messages. These are done with a straightforward implementation of Slack’s Workflow feature, that allows you to trigger behaviours from events in your workspace. Here we are looking at sending a message to new members of a given channel, helping to point them in the right direction and discover any additional channels they might be interested in. When paired with user groups and default channels, this can create a powerful workflow:

Invite your colleague to Slack ➡️ Add them to the right user groups ➡️ The user will automatically join the relevant channels through default channels ➡️ By joining certain channels, the user is sent a relevant welcome message 👋

With a custom welcome message you can introduce:

Active projects and other channels they might want to join (you might have a #all-pets channel, for example 🐱)

Any relevant sub-teams or user groups and their @ handles

Regular or recurring events and calendar invite links (e.g. daily stand up or monthly team huddles)

Links to useful documents like onboarding or the company strategy video

You can set up the workflow by yourself using the ⚡️icon next to the message box in the channel you want to welcome people to and searching "open workflow builder". From there, create a new workflow, giving it a name and using a "New channel member" trigger. From there, select the channel, click "Next", then select "Add Step" and "Send a message". Use the "Person who joined the channel" magic variable, and write your message.

I have also created a template workflow you can download here (call the file welcome_message.slackworkflow) and import directly into Workflow Builder using the "Import" button. For more on Workflow Builder, check out this guide from Slack.

A bonus feature worthy of a mention is email-to-channel integrations. Even the most well-intentioned teams may still find they have regular company updates or integrations with third party services that only work through email. While you could set up a shared inbox, or auto forwarder to each of your team members, it might be easier for you to get those emails sent directly into a Slack channel.

To set up an email address for your channel take a look at this guide from Slack.

Note: to keep alerts and automated messages to a minimum and out of the critical path of your colleague’s discussions, you might want to set up an alerts channel, for example: #finance-alerts.

So there you have it, how to make Slack work harder for you and your team through clearer channel naming, user groups, and Slack Workflows to create automated welcome messages.

Do you have tips for helping empower your teams to work more openly and collaboratively in Slack? Tweet me your suggestions on @chrishutchinson, I’d love to hear them!

Chris is a Lead Engineer at Made Tech, improving digital services for UK citizens through better technology delivery. He also co-built and maintains The Operator, a Slack app for unleashing the knowledge in your private channels, improving discovery through knock-to-join private channels. He also maintains Slack Testing Library, an open source library for quickly writing powerful integration tests for your custom Slack apps.

How to make Slack work harder for you and your team

Channels, user groups and welcome messages

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.

Chris Hutchinson

Latest weeknote

Projects

Fringe Engineering

Slack Testing Library

Tomorrow's Papers Today

To Do × RSS

Train departure board

Talk: React Testing Library

Paint your own Christmas tree

UK Air Quality Alexa Skill

Journal

How to make Slack work harder for you and your team

Finding your documentation groove

Hacking around with JavaScript and Shortcuts in iOS 12

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