Panic!
In The Toolshed

matt-dray.github.io/government-toolshed

Matt Dray, June 2023

tl;dr

Share your tools

• The ‘too long didn’t read’ for this talk is very simple and you already know it: if you make something helpful, then share it with others. Share it even if it isn’t completely helpful yet.
• This will help reduce duplication, improve quality and improve efficiency.
• By ‘tools’ I’m mostly thinking of software, packages, that sort of thing. But it also applies to stuff that isn’t code as well.

An experience

• I could just leave it at that.
• To add credibility I’ll tell you a little story about a tool I created and shared, and the things I wish I’d thought harder and earlier about.

• In 2021, which feels like 100 years ago, the Government Analysis Function created new (and very good) guidance for releasing statistics in spreadsheets.
• My team published a number of spreadsheets on GOV.UK, but none were compliant. They used cell colour as data, had empty columns, used multiple headers and had footnotes hidden under tables. Classic non-accessible stuff.
• In addition, the production process was point-and-click and wasted a lot of time.
• There was an opportunity to use the new guidance to overhaul our publications.

remotes::install_github("co-analysis/a11ytables")

a11ytables::create_a11ytable(
  tab_titles,
  sheet_types,
  sheet_titles,
  blank_cells,
  sources,
  tables
) |>
  a11ytables::generate_workbook() |>
  openxlsx::saveWorkbook()

• I started with some reusable R functions to apply the new guidance consistently, which later meant it was worthwhile to create a package so it could be more easily maintained and shared.
• The package is called {a11ytables} and this is an example of what it looks like in use.
• What does the package do? You give it your tables of data, along with some metadata like worksheet titles, and it automatically creates an xlsx spreadsheet that complies with the guidance as far as possible.
• It does the hard work for you to structure and style your spreadsheets in a compliant way, basically.
• I should say that the Python package ‘gptables’ existed at the time, but it hadn’t yet been updated for the new guidance (it has been now) and there was no native R solution.
• R users are special, after all, and they deserve the very best.

• So, having put in a little bit of effort already, and knowing that other departments needed to comply with the new guidance as well, it made sense to make the package easy to use, universally accessible and to tell other people it existed.
• First, this involved making some half-decent documentation. The screenshot here is the package’s website.
• Then I spoke to likely users, both internally (i.e. at an NHS-R webinar, at a GSS Champions quarterly meeting, to a Scottish Government R conference) and externally (i.e. a talk at EARL conference 2022, blog posts, social media).

Success!

• It did what I wanted it to do
• It’s in use across government
• It’s been improved by feedback

• I used it to successfully create the spreadsheets my team needed to release. The lowest bar!
• The package is now in use across a number of organisations (CO, MoJ, ONS, DfT, Scot Gov, etc).
• It’s also now referenced now from the Analysis Function spreadsheet guidance, so that’s nice.
• I had lots of great input and ideas from colleagues, and inevitable bug-catching, which helped improve the package.

Panic!

• Where’s the maintainer?
• Should it move to another repo?
• Should {a11ytables2} exist?

• And I’ll now I’ll deflate my ego. Despite some success, there are some complications.
• I wrote the package in a department that I’ve now left. My access to the GitHub repo is diminished and it’s no longer a priority. There are no other maintainers.
• How does this look from the user perspective? Will they think it’s stuck in liminal space or abandoned?
• Should I have asked earlier to transfer it somewhere more central than my division’s GitHub organisation? Where would I have transferred it to?
• Moving a package means you have to think about awkward things like licensing, broken URLs, the burden on the new owners, etc.
• {a11ytables} is based on the {openxlsx} package. An {openxlsx2} package is maturing and has better support for a number of features, like automatic font colouring, and should make for more readable code on the backend. So should {a11ytables} be updated? Or is this the chance to make an ‘{a11ytables2}’?
• More importantly I think it’s a terrible package name, but it’s too late to change it.

Reflection

• I could probably have thought about these things earlier. So here I am telling you to think about these things while you can.
• If I were to tease this out a bit, the experience boils down to three things: think sustainably, try to centralise, and make sure to advertise.

1. Think sustainably

• Build modular things
• Write good documentation
• Plan for your loss

• First, what do I mean by ‘think sustainably’?
• Make smaller, simpler things that are easier to maintain and have a greater chance of being used more than once in multiple projects.
• Make it easy for you and others to understand the code.
• Do what you can to make it as easy as possible for other people to use and develop it if you disappear.

2. Centralise

• Make it discrete
• Make it easy to find
• Pool your tools

• Second was ‘centralise’.
• Bring together your code in one place; ideally into a package structure if it makes sense. Make it into a defined ‘thing’ rather than ‘a bunch of stuff in a folder’. You should be able to point to it as a single URL or filepath at worst.
• Get it off your local drive and made available to your team, to your org, to the government, and beyond.
• Tools created on government time belong to the taxpayer. Making it open improves transparency, but also makes it much easier for others to collaborate and ask questions. (Yes, I understand that certain things are sensitive and it’s not easy to do make them freely available, but try to default to openness where possible.)
• Try to surface tools in one place, at team and organisation-level at very least. The people most likely to need your tools are probably at these scales. But why stop there?

3. Advertise

• Talk to people
• Expose duplication early
• Build a community

• And third, ‘advertise’.
• How can anyone find your project? Talk about it in internal networks, at Coffee & Coding, etc. Expand out to external events even if you don’t think there are users there; try Slack, or these Data Science meetups, or even external events. You could inspire someone else.
• The sooner you start talking about it, the sooner you’ll find out if it already exists.
• Encourage questions and collaborators and build a little community to help improve the thing.
• This is not about ‘marketing’, ‘clout’, or impressing people. It’s about making people’s lives easier, including yours.
• The smart ones among you will realise that this is pretty meta: I’m advertising while I tell you to advertise.

It’s not just me

• Of course, this isn’t new.
• Turns out that there are government principles that relate to these ideas already.
• These principles focus more on digital services, but we can co-opt them for ‘tools’.

Gov Design Principles

• Do less
• Iterate, then iterate again
• Make things open, it makes things better

• These three points from the Government Design Principles are helpful in the context of writing tools as well.
• Principle 2: ‘If we’ve found a way of doing something that works, we should make it reusable and shareable instead of reinventing the wheel every time.’
• Principle 5: ‘The best way to build good services tools is to start small and iterate wildly.’
• Principle 10: ‘Share code, share designs, share ideas, share intentions, share failures.’

Tech Code of Practice

• Be open and use open source
• Share, reuse and collaborate

• The Technology Code of Practice echoes these sentiments.
• Criterion 3: ‘Publish your code and use open source software to improve transparency, flexibility and accountability.’
• Criterion 8: ‘Avoid duplicating effort and unnecessary costs by collaborating across government and sharing and reusing technology, data, and services.’

A metaphor

• You’ll have noticed the idea of a ‘toolshed’ as the theme of this session.
• I’m going to humour Mia, who I think came up with this metaphor, by spelling it out more literally.

• Is this the current state of the government toolshed?
• We know there are tools in use across government that others might be able to use or contribute to, but they’re not organised.
• Maybe some are multifaceted instruments, like the Swiss Army knife; maybe some are more blunt, like this tomahawk; maybe some are overcomplicated, like this knife that has a picture of a… knife… on it.
• You get the idea. It’s a metaphor. What the heck is available and how the heck can I find it?

• Could this be the future state of the government toolshed?
• What if we could organise and arrange our tools so everyone can more easily find and use them? What would that look like for us at a government-wide level?
• Fittingly, this image has some empty spots to be filled and also some tools that fill a spot, but don’t quit fit the spot. Room to develop?
• But maybe we need something more like a Toolstation (not sponsoring this talk) that has a catalogue that you can peruse (other tool vendors are available).

• Let me give you an example of the simplest possible format that this take: it could just be an up-to-date, centrally managed list.
• This is an example hosted in a GitHub README. It’s a list of ‘awesome official statistics software.’
• There are many ‘Awesome’ lists on GitHub for all sorts of things. They’re usually fairly ad hoc. But you can immediately see what’s on offer and it’s status.

• Another example is the more formal ‘CRAN Task View’. These are lists of R packages that are related to specific named tasks.
• This one is for official and survey statistics, for example.
• Wondering out loud: do you think this is something we should do, at very least?
• I’m not saying this is the only solution. Maybe common resources should have a high-level home; maybe GitHub repos could go under one GitHub organisation? You might hear a bit about that from the NHS-R talk in a minute.

tl;dr

1. Share your tools
2. Sustainabilise, centralise, advertise
3. How best can we surface and share tools?
4. Don’t panic!

• Anyway, to recap, I’m telling you to do obvious things like ‘share you tools’, but also to think about how you can make that easier for yourself in future.
• A question for the audience is to think about ways we can collectively share what we’ve made.
• And if you don’t care about anyone else, then at least prevent future-you from panicking.
• I’ve been Matt Dray, thank you for coming to my therapy session.

Links

• These slides and their source
• Blog about this talk
• {a11ytables} docs and source
• The Analysis Function’s spreadsheet guidance

Credits

• Ashim D’Silva on Unsplash.
• Cesar Carlevarino Aragon on Unsplash.
• DM Serif Text by Colophon Foundry.
• Spline Sans Mono by Eben Sorkin and Mirko Velimirović.
• Quarto by Posit PBC.