Over the past year I built a generative AI tool that hooked me on high-convenience, ultra-processed article summaries. It made it easier to consume ideas, but didn't help me think more intentionally or more critically. Now, I'm rebuilding it as a high-friction tool to counter AI-induced cognitive atrophy. Only when I built a connector giving Claude Desktop access to my tool did I discover I'd been approaching it all wrong.

18 months ago I was interested in using AI as a second brain. I tried early versions of mem and Reflect, but found they didn't really work for me. So, I built a simple, AI-supported reading app to help me capture and cross-reference content from across the web.

For 12 months, the app served me well, generating condensed overviews, extracting highlights and themes, and connecting disparate content, as well as capturing my own thoughts.

After a while, I struggled to get value from my captured content. I was using the app as a crutch rather than a growth tool. I was relying on the automated summaries more than I had intended, and having to hunt down content to read again in order to recall insights. Text and conversational search didn't really deliver the depth of understanding I had hoped for. I wanted to internalise the content I saved so I could build the knowledge myself. Instead, the AI was reading it for me and spitting out a middle-of-the-road overview, and I wasn't getting much out of it. Since launch I've written notes against fewer than 3% of captures. I knew I hadn't hit the mark, yet.

Building an MCP server for the app led me to the realisation that I was misusing AI. Giving Claude access to what I'd saved meant the content was able to break free from the bounds of my app. When working on a write up of a new product feature, Claude connected it back to the MAYA principle, from an article I had captured many months prior. I hadn't thought about it myself, but Claude, using my app's MCP server, drew the connection I'd missed, contextualising the content, not just summarising it.

A growing body of research shows that heavy use of LLMs can dull reasoning and memory through "cognitive offloading", the outsourcing of thinking to digital tools. Experts fare better than novices, but the evidence shows that less cognitive struggle leads to diminished opportunity for mental engagement and critical analysis.

In my own experience I've felt the dopamine hit of getting an instant article summary, and a quick answer to make me sound smart. My app today feels like ultra-processed food, it can be satisfying in the moment, but hollow over time. The research made me consider what a tool that actively demanded cognitive attention might look like.

So I'm pivoting: from a capture-and-summarise reader tool, to one designed to make me smarter. I want an app that acts as an antidote to cognitive atrophy, one that is actively supporting me, not subtly undermining me.

What might that look like in a product? My top priority is to avoid over-reliance by limiting access to AI-generated insights until I can demonstrate understanding and critical thought around a piece of content.

To achieve this, I'm starting with an experiment that prioritises high-friction "productive struggle" over instant gratification, requiring me to write a short reflection of the content before it gets stored in my app's long-term memory (only long-term memory content can be surfaced in the future). Writing is a powerful tool to help us think, and there is evidence that intentionally adding latency may "scaffold deeper cognitive processing". Using writing as a gate means if I want to find and use this content later, I need to engage with it now, experimenting with how AI agents can assess that writing using a panel of tailored experts.

There's an inherent tension here in using AI to reduce my reliance on AI. The writing requirement forces cognitive engagement. I'd rather an AI push me to think deeper than do the thinking for me.

How will I know it works? In the experiment I will be monitoring:

Capture rate – does friction discourage me from capturing content?

Recall – do I retain and apply more of what I read?

If you have thoughts or ideas for me, or on the wider domain I'd love to hear them. If you enjoyed this post, please consider sharing it on Hacker News.

P.S. I am not making my app generally available right now, it is designed for me (Selfish Software as Edmar Ferreira calls it), but if it's something you do think you'd use, please let me know!

Designing with friction: A cure for AI-induced cognitive atrophy

Over the past year I built a generative AI tool that hooked me on high-convenience, ultra-processed article summaries. It made...

APIs are (sort of) over; and the new era of work

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

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

We've been preparing for a big piece of new work this week, which will entail building new capabilities and integrating with existing ones, in some cases rethinking how they work today. In order to encourage the discussion, I put together a document reviewing the requirements and proposing one way we could approach our data model ("data model" here being the objects and entities that we will have to flow through the system). 

I knew the document had flaws and there were areas I had intentionally left light on details. Thankfully, the straw man did exactly what I wanted, it gave us something to critique, poke holes in and we have ended the week with both a much better (shared!) understanding of the problem space, but also a robust list of next steps for us to tackle in the next couple of weeks!

I spent some time this week (and a little last week too!) mobbing on a lightweight implementation of feature flags for our application. Three of us spent a couple of days using VSCode Live Share to collaborate on the design and implementation. This was great fun, and not only did it give the whole group a great understanding of what we'd built (and kept us honest around following proper test driven development), it also gave each individual something new. For me, I spent a lot less time writing code, instead describing my thought process and helping guide the rest of the team through the exercise. This gave me an opportunity to explore the way I talk about engineering concepts, and find some new methods to help land complex ideas.

On the surface, mobbing often feels like it will be time consuming and that it'd be easier to just stick on your headphones and build it yourself, but every time I try it I come away impressed at how much we build, often how few lines of code it is compared to my expectations and how much more rounded and complete the implementation is. Having multiple people on the team involved in the design and initial implementation also makes ongoing maintenance and enhancements easier.

I've been working on an iPhone and iPad app over the past few months (built entirely in SwiftUI) that displays the latest UK newspaper front pages as soon as they're published, usually from around 10pm the night before. I'm finally ready to show it to a few more people and have launched a wait list for anyone to join the first beta! If you'd like to get involved and help me shape the app ahead of the first public release, head over to the Tomorrows Papers Today app website and register your details – https://www.tomorrowspapers.app. You can also follow the account on Twitter if you want more regular updates. Thanks!

Weeknotes for week beginning 21st June 2021

Over the past couple of weeks my team and I have been getting our heads into the nuts and bolts of what we need to do to improve our process around continuously delivering code to our users. We’ve been looking at our contribution process, how we pair when making changes to our codebase, how we might use preview environments for quicker user testing, where feature toggles allow us to ship incomplete code to production in a safe way, and how we have confidence in how our application performs once it’s in the real world.

All of this is typically excites us as engineers, but the value isn’t always clear to our stakeholders. Beyond the practicalities of how we might evolve our process, we’ve spent a good amount of time discussing what will actually add real value, and whether it’s possible to incrementally practice continuous delivery and start having an impact sooner.

There is a lot more to think about here, but a comment from one of my colleagues stuck with me this week, as they reminded me of the value of decoupling deployment and releasing as a way to reduce risk. 

I had a few days off last week (hence the short break in my weeknotes!). It was lovely to disconnect and head to the Welsh coast.

Weeknotes for week beginning 31st May 2021

Seeing small improvements starting to pay dividends at work is incredibly satisfying, and even though they’re small, the positive shift in the team’s attitude increases the likelihood of further improvement, and future success. I’m currently thinking on how to get teams to open up more in group sessions, how get everyone to present and challenge ideas, and what I can do, as a member on the team, to encourage that more.

I took my first trip into the Made Tech offices this week, my first central London visit since March. It was great to see the working space and to meet a few new colleagues in person. I’m looking forward to a few more opportunities to visit in the near future, especially with the vaccine coming soon(ish)!

For the past few weeks I’ve been toying with one of my side projects, a service that offers a way for users to connect all (read: some, for now!) their workplace tools in one place, and push it all into a private view in Slack — think of it as your own personal work dashboard, right inside Slack. It runs on a mix of Vercel, Next.js, Supabase and NextAuth, and I’m hoping to be able to launch an early beta version in the next couple of weeks. I’m sure I’ll post on Twitter if I make it that far!

I’m taking some time off for most of next week so, depending on a few things, my weeknotes may take a short hiatus too.

Weeknotes for week beginning 17th May 2021

This is something that seems to come up time and time again in software engineering, and something I’ve been thinking about a lot this week. When a system is struggling, slowing down, or otherwise giving you and your team headaches, all too often the solution teams reach for is to tear it down and start again from the beginning. In almost every scenario I’ve seen this, hindsight has shown it to be a big mistake.

I totally understand the desire to build again, the sales pitch is easy: “we can do everything we can do now and more, that we can release faster and that uses all the latest and greatest technologies – our customers will love it”. I’ve even fallen into this trap more times than once. Inevitably though, it takes longer than you expect, you end up with a small percentage of your original product feature capabilities, and many of your processes haven’t gotten any faster. Often the existing system keeps causing you so many problems you never truly get to focus on the new one, leaving you with two services that aren’t fit for purpose.

There are, of course, cases where building again can be the right choice, but so often my experience shows that critically reviewing what you currently have, looking not at the code and the pipelines, but internally at you and your team, reveals more about the headaches you’re experiencing.

Perhaps you aren’t refactoring as you go. Perhaps tech debt (I prefer the term product debt) is getting out of hand. Perhaps you haven’t been keeping your dependencies up to date and they’re introducing critical security issues. In these scenarios replacing the code and technologies rarely helps in the long run. It’s a bit like buying a brand new car, treating it badly for a couple of years and having constant issues with it, and thinking that just buying a new car is going to solve all your problems. It will for a short while, but if you don’t change your approach, you’ll be back at square one in another couple of years.

Instead, taking time to plot a course to get yourself out of that hole, to develop that maintenance and stewardship mindset in yourself and your team, and to bring the best of your existing system along with you, will likely get you to a much better position, and in a way that you can practically support into the future.

I have lots more (currently unstructured) thoughts on this, likely worth a full blog post at some point, but for now – tell me your stories (good and bad!) of rebuilding software from the ground up, I’d love to hear them @chrishutchinson.

This past couple of weeks I’ve been playing Civilization V with a couple of friends. I stumbled over this podcast – Civ Stories – in which the hosts tell stories of games that have gone on late into the evening, and all too often have had absurd or ridiculous outcomes. Playing Civ again has been fun, although I am fairly awful at it for the time being. Practice makes perfect they say!

Weeknotes for week beginning 10th May 2021

My new team have been hard at work over the past six months developing new tooling for Hackney Council. Having spent the first 10 days on the team getting to know everyone and understanding what was working well, and what wasn’t, one theme kept coming up again and again – the JIRA setup. I spent much of last week refreshing my memory of the JIRA admin interface and putting together a proposal of how we could make more of the tooling at our disposal, including improving our Slack and GitHub integrations and making the tool work harder for other disciplines in the team, including designers and researchers. 

I welcomed support from colleagues in other teams who have been through the same process and one piece of advice seemed particularly relevant:

With JIRA there’s always going to be someone complaining that it doesn’t work for them, or they don’t like the new process.. Think about the smallest workflow change you can make which will deliver the biggest value and repeat that process iteratively, like you would on any other work you do.

We’re going to try our first iteration of the updated JIRA setup this week, and review at the end of the next two sprints.

For a few weeks now I’ve been putting some energy into an iOS app for the popular #tomorrowspaperstoday Twitter hashtag, bringing the latest UK newspaper front pages to your device as soon as they’re sent to print the evening before.

It’s not live on the App Store just yet because I’ve been struggling to get it through Apple’s strict approval process. Not wanting to spend too much time on it before first judging if there’s any real audience, I prioritised getting the smallest set of functionality live for my first publish. That was rejected, as with all my subsequent attempts as it breached Apple’s review guidelines (section 4.2 for those who are curious) around minimum functionality, in that it should “provide features, content, and UI that elevate it beyond a repackaged website”. This has been frustrating, as I am heavily relying on Home Screen widgets, something that a website can’t provide, and in recent builds I have added push notifications, something websites also can’t do on iOS.

I submitted it for review again this weekend, so fingers crossed it’ll make it through without appeal!

Note: I’m also looking for beta testers, who want to test the app now (before it goes live), and to test new features as I work on them. If you’re interested, do reach out to me on Twitter @chrishutchinson. If you’re just interested in knowing when it’s live, you can follow @papers_tomorrow.

Weeknotes for week beginning 3rd May 2021

This week started off pretty quietly, but by Thursday I had landed on my first formal project at Made Tech. There'll be more to come on that in the coming weeks I'm sure, but for now I'm getting my head into the problem space and looking forward to some interesting challenges. One bonus, the tech stack is Next.js with TypeScript so, at least initially, I can focus on the ins-and-outs of the client's needs and how to approach a different style of working, rather than having to up skill on any entirely new language or framework. The new project kept me pretty busy by the end of the week.

During my time at The Times I worked on an open source project for generating templated images (intended for use on social media) in browsers, and on the server using Node.js – CardKit. It hasn't had much activity in the past year or two, but I'm aware of people still actively using it. With that in mind I've been tidying it up, bringing the core dependencies (Webpack, React etc.) up-to-date, and getting it ready to release a v3 which should provide a stable base for any future work I choose to do on it. The main improvements I'd like to make is the way it handles text (wrapping and better formatting), and enhancing the UI so creating 'templates' doesn't necessarily require coding skill.

As I said last week, I'm finishing reading A Civic Technologist's Practice Guide by Cyd Harrell, and this particular quote stuck with me this week:

Compound improvements build on each other over medium time frames (say ten years), resulting in a situation that is many times better than it was at the start, even if each individual improvement is small.

It felt really important to recognise the value of small incremental changes, rather than putting focus on big evolutionary changes. Instead, evolution is the process of making gradual changes towards a given goal (which may move as those changes are being made). In programming, tasks like regular refactoring, ensuring dependencies are kept up-to-date, and keeping individual contributions small, are all ways we can better the code we write, work more flexibly, and ultimately create a better product or experience for our customers. I think this applies to technology and engineering as much as it does to every day life.

Weeknotes for week beginning 26th April 2021

A lot of the codebases we work with at Made Tech are in C# using .NET Core. I've only ever dabbled with C# in the context of the Unity game engine, so I spent a bit of time this week getting a bit more familiar with the syntax. Instead of throwing myself into the documentation, a colleague recommended I try a 'koan', an almost story-driven approach to learning a new language. I followed this koan, which starts simple with booleans and strings, and builds up to more complex language features, including delegates, globalisation and more.

It was an interesting way of trying out a new language and certainly gave me a good overview of the core components. My learning style really leans towards actually building something with a language to get a better understanding of it, so that's next up on my list with C# and .NET Core.

If you're interesting in trying a Koan, Made Tech host a list of them here, but you can also just search for '<language name> koan' for most languages and you should be able to find something suitable!

Modernising legacy tech – the iPod Classic edition

After a few weeks wait, all the parts I had ordered finally arrived to give my iPod Classic a new lease of life. I picked it up second hand earlier this year, but found the battery wasn't holding charge beyond a few hours, and the physical hard drive only compounded the problem. I picked up a new battery from iFixit, and an iFlash-Quad, which allowed me to swap the 160GB hard drive out with up to four Micro SD cards!

Having finally built up the courage to follow the battery replacement guide (rated 'very difficult' 😱), I was able to swap out the two parts without a hitch, and so far things are looking good ⚡️! An added bonus is that the iPod is now much lighter than before, given the weight difference between the old hard drive and the new storage board.

My plan with the iPod is to create an offline device, for when I feel I need to disconnect from the world. I'm going to fill it with B-sides, and other obscure music that typically isn't available on streaming platforms. Any recommendations? Do let me know!

I fixed a bug this week, the result of a website migration that moved from a Gatsby static site to a WordPress hosted theme. The bug report was something along the lines of "Help! The website won't update for me, but it will for other people, and it's been this way for two weeks!". Some theories had been thrown around: DNS caching, CDN behaviours, amongst a few others, but having dug into the issue further it became apparent that these weren't the culprits. Some remote debugging later, on the only browser I had access to that would reliably reproduce the issue, it turned out that the old Gatsby site had been using a plugin that made it work offline, via a service worker. The new WordPress website on the other hand, didn't have one. Checking up on the documentation, it turns out service workers will hold onto the last healthy version, if the URL it was registered at now returns a 404, as it was in this scenario. 

If your new worker has a non-ok status code (for example, 404), fails to parse, throws an error during execution, or rejects during install, the new worker is thrown away, but the current one remains active.

– The Service Worker Lifecycle | Web Fundamentals | Google Developers

This meant any browser that had the original service worker was getting the old site, and network requests were being intercepted and served from a local cache, preventing new content from appearing. 

The solution: register a new service worker at the original URL that passed all traffic through to the network, resolving the initial worker 404, and ensuring those browsers with a service worker could update it and fetch content from the origin server again. Then, we added some additional code to deregister all service workers, to prevent the odd middle-man behaviour where the service worker was intercepting all traffic just to forward it on to the network.

The lesson: if you're going to implement a service worker, be damn sure you have a good reason, and make an effort to familiarise yourself with the scenarios in which a service worker will (or won't) update!

I'd picked up Cyd Harrell's A Civic Technologist's Practice Guide a few months ago once I knew I was starting at Made Tech, but hadn't got around to finishing it. I really love the way it's written, and there are some really practical tips for how to have a meaningful impact in government technology.

I usually like to have a more engineering-focused book on the go too, and I have started dipping into Mazes for Programmers this week. It's a great balance of quirky curiosity and challenging algorithms.

Weeknotes for week beginning 18th April 2021

For those who follow me on Twitter, you'll know this was my first week back at work following a short hiatus after leaving The Times and News UK. I've started as an Engineer at Made Tech, and have made the jump from publishing to the public sector. I'll be honest, one week in I don't have any huge discoveries to share, only that there are elements of public sector (from what I've seen so far), that are scarily similar to publishing, and huge amounts that seem to be different.

I took this job as a chance to challenge myself, and try something new after almost seven years at The Times, so I'm really excited to get stuck in and start learning more.

Perhaps the biggest surprise (a pleasant one, I promise) after joining Made Tech was the quality of their onboarding process. An entire week is dedicated to taking all new starters through their HR and company processes, but also introducing us to their company culture, which is heavily reliant on giving regular, open, and honest feedback. Not only does Made Tech encourage this feedback process within its own team, but also within the teams they work with in local and central government. After only a week I can already see how this impacts the team day-to-day, as all-staff meetings, showcases, and company updates are all filled with open discussion, where nothing is off the table. A real win for communication and transparency.

On Saturday, with the sun shining, I took the chance to visit Kingston upon Thames, London. I was planning to take some photos of the river, the parks, and some of the lovely architecture that the town is blessed with. In the end, despite enjoying the walk, and the weather, I came away disappointed with the photography opportunity. Everywhere I looked there was corporate logos, bins overflowing with branded packaging, and a general sense of homogeneity. Perhaps I'd gotten used to how quiet things had been during the UK's various COVID lockdowns, but it really seemed a shame. I'm sure I'll head back there later in the year and find some hidden gems, and feel much better about it!

I've started listening to The Federal Management Playbook this week. More to come on that in future weeknotes.

This is the first time I've 'weeknoted'. I've read about the theory and religiously follow the weeknotes of others, but have never done it myself. A new role, especially one working closely with public sector organisations, seemed like a perfect moment to start. I would love your feedback, or just to know if you're reading. Let me know on Twitter or LinkedIn.

Weeknotes for week beginning 12th April 2021

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

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

chrishutchinson.me

Designing with friction: A cure for AI-induced cognitive atrophy

APIs are (sort of) over; and the new era of work

How to make Slack work harder for you and your team

Note taking and explaining systems

A straw man, the benefits of mobbing and a new app beta

Continuous delivery and the Welsh coast

Small improvements, new offices and side projects

Making the most of what you’ve got

Improving JIRA workflows and publishing on the App Store

A new project, an old project and compound improvements

Learning C#, modernising legacy tech (iPod edition), and tricky service workers

Back to work; a culture of feedback and learning; corporations taking over

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

My WordPress Renaissance