As we undertake a lot of work based around knowledge-sharing and best practice, we’re looking into the concept of ‘playbooks’ as one proven way to share practical lessons. Our aim is to ensure that none of our learning is lost, and that it is shared with practitioners who face similar challenges in the future in as useful and accessible a way as possible.

What is a playbook?

‘Playbook’ is a word that’s used a lot these days, by tech and management people. They’ve borrowed it from the world of sports, where the idea of a book telling you ‘how to play’ is a more straightforwardly obvious concept.

If you find this terminology a bit too hipster, though, you can think of them by the less trendy terms of ‘manuals’ or ‘toolkits’ — though a playbook does have the advantage of sounding like a lot more fun than a workbook.

Whatever the name, what they aim to give you is a collection of repeatable plans and tactics for responding to typical challenges. As such, they can be absolutely invaluable as an internal company tool; and we think they can also help in sharing knowledge between organisations.

In either case, a well-managed playbook would be easily available to employees, widely used and regularly updated.

Content

Playbooks might be for one department (like sales, or design) or for the organisation as a whole. They typically contain several different kinds of content, such as:

• Plays (or guides), detailing the steps that need to be taken to achieve a goal or cope with a scenario
• Scenario or problem definitions, describing things that may happen, or go wrong; how they are caused and how they are identified
• Ingredients: details of the resources needed and the costs associated with them
• Case studies: Written summaries of real life projects that have come up against scenarios and utilised similar plays or guides to solve them
• They also usually contain some signposting or navigation method, such as tags or categories — or one of our favourite methods, the questionnaire.

Questionnaires as a content discovery method

One great way to ensure that people are seeing the most relevant content in an often hefty playbook is to use a questionnaire that leads the user to the precise content they need at that particular time.

By answering a series of questions, the visitor can provide some information on their own situation, and in return be delivered the most relevant content.

For example, Atlassian’s health monitor, part of their playbook, asks you to rate how well you feel your team is doing on certain attributes, such as shared understanding, decision making, and dependencies.

Once the questionnaire is completed it offers suggested plays and lets you assemble and share your own action plan.

What goes into a useful playbook?

Practical advice that is specific to your situation is often the most helpful, and this where playbooks really shine.

A well thought-out playbook, with a questionnaire that asks the right questions, can make available clearly-defined, tailored content that is domain-specific. This means that the reader doesn’t need to work hard to apply generic advice to their situation, nor untangle clumsy metaphors.

Playbooks often solve the problem of ‘how do you know what you don’t know?’, with tried and tested solutions to known problems.

A playbook should be designed with the target audience in mind — and that audience can potentially be a narrow one, operating solely within one domain or department — offering rich advice based on experience. It should empower people to achieve their goals, solve their problems and, ultimately, shape the culture of their organisation.

A well thought-out playbook will become invaluable to its users, and consequently they will want to keep it up to date and useful.

For this reason many playbooks have a method of feedback to aid continual improvement, such as rating a page based on its utility, open feedback methods or collaborative wiki-style editing.

Where we’re working with playbooks 

Local Digital FOI

One of the prototypes we pursued as a result of our research into how councils manage Freedom of Information requests was a playbook, fronted by a self assessment questionnaire.

We identified a need where teams want to improve their service but don’t necessarily know where to make improvements (eg, should they invest in better software, train staff, or revamp their processes?).

Our prototype playbook asked questions to determine the shape of the council’s FOI service, which then presented guides and descriptions of potential problems relevant to their case.

We’re looking at developing this idea further in a future project. If you work in a local authority, and are interested in partnering with other local authorities in a Local Digital funded project to develop this prototype into a resource that could be used across the sector to improve services… please do get in touch!

Public Square

Our Public Square work focuses on citizen engagement in local democracy, and we think a playbook could form a key part of this project.

We’re planning a series of guides, case studies and research presented in a clear and accessible playbook format, to be used by councils and other public sector organisations where greater citizen involvement in decision making is a goal.

Our favourite playbooks

There are hundreds of great examples, but here are the ones we’ve singled out as particularly strong:

• Thoughtbot’s playbook for software design and development
• GV’s design sprint playbook
• Atlassian’s team playbook

If you’ve been working on a playbook, or your organisation already has one that you think is doing interesting things, please do let us know.

—
Image: Playability.de (CC by-nc-nd/2.0)

WhatDoTheyKnow Pro is our Freedom of Information service for journalists, and campaigners, and we’ve recently rolled out some major changes to the request sidebar to make reading, navigating, and classifying Pro requests a lot easier.

Since the very first Alpha version of WhatDoTheyKnow Pro we’ve been receiving feedback from our users, which we have been feeding directly into our future development plans. The sidebar changes are the first round of changes that have come as result of direct Pro user feedback, and there will be more to follow.

Current state

In WhatDoTheyKnow a member of the public can send a Freedom of Information request to an authority, which they receive in the form of an email. The request, as well as any replies or follow up from the requester, or the authority, are published on WhatDoTheyKnow. If the request is made by a Pro user, they have the added option of making a request private for a limited time.

In the request process we observed the following:

• A new response from an authority goes to the bottom of the thread (the bottom of the page)
• The user interface for updating the status of a request is located at the top of the page (a request’s’ status is a way of keeping track of where it is in the request process – for example ‘awaiting response’, ‘needs clarification’, or ‘refused’)
• A longstanding or complicated request will often consist of many, many messages. So scrolling to the bottom of the page to read the most recent response, then back to the top to update its status involves a lot of interaction that we can remove.

We can’t say for sure that a user will always be at the bottom of the request thread when updating the status of a request, but we can safely assume they are sometimes.

Goals

For these changes we set ourselves the following goals:

• Speed up the process of updating the status of requests
• Improve the experience of navigating requests with a long history.

In previous research we established that a typical workflow for dealing with request responses is:

Get reply → Read reply → Take action (typically reply, or update the status of the request)

It’s a short, three step process, but a busy user catching up with a backlog may do this hundreds of times a day, so if we can optimise this workflow we can save a lot of time and frustration.

So what have we done?

For desktop users we’ve made the sidebar controls (where the ‘update status’ button is) “sticky”, so it will follow you as you scroll up and down the page, meaning you can update the request status from any position on the page. This really helps as requests get longer, as you no longer need to scroll back to the top to classify the latest response.

We’ve added new message navigation buttons. This is to enable you to move through a request thread message-by-message by clicking the up and down arrow buttons, or using the arrow keys on your keyboard. We’ve also added a counter so that it’s easier to see where you are in the list, and to go back and forth to specific messages.

We’ve also taken this opportunity to make some key information about the privacy of your request visible at all times (this was previously hidden behind a click), and to tweak the design of the sidebar – making it easier to read and removing some visual noise.

More to do

We’re looking at a way to add similar functionality to mobiles and other small screen devices. As screen space is limited it will require a separate design process.

We’re aware that the problems we’re trying to solve aren’t unique to our Pro customers, so if the features work, and are well received, we’ll be making a similar feature available to all WhatDoTheyKnow users in the future.

Keeping in mind that as our public users have different needs to our Pro users there are some design challenges to overcome beforehand. For example – the public request page has more features to help less-frequent users, because we’re keen to ensure that everyone can participate in the FOI process, not just experts. Conversely, Pro users are by their very nature more likely to require less guidance. We’re going to need to do more research on this shortly.

Got some feedback?

Whether you’re a WhatDoTheyKnow Pro customer or not, we’d love feedback on this feature — or any other. Drop us an email to pro_team@whatdotheyknow.com.

We recently made some changes to our Freedom of Information software, Alaveteli, that makes it twice as easy for partners to change the look and feel of their site. This post goes quite in-depth, so it’s probably best suited for designers, developers and other technically-minded readers

This year we embarked on a ground-up redesign of Alaveteli’s theming capabilities to make customising Alaveteli easier and faster. We used a mixture of techniques to try to achieve this and since releasing the update we’re happy to have seen a decrease in the complexity of our themes, and the time we spend making them.

Alaveteli, our Freedom of Information platform is one of our most deployed software packages and each deployment requires some customisation, from simple branding changes to complex functionality to support a country’s FOI process. This is either done internally by our own developers, or our partners take this on themselves.

An Alaveteli deployment consists of two things, the core: the guts of Alaveteli with no customisations, and the theme: the aesthetic and functional customisations made to each site. We ship Alaveteli with a fully-featured base theme that gives partners a good starting point to work from, but they can also start their own theme from scratch.

After talking to our partners and the Alaveteli team we felt that the process of theming was too complicated and involved. It required a lot of knowledge of Alaveteli’s inner workings, was coded in a way that made it hard to understand, and almost always required the intervention of a front-end expert, even to make trivial changes.

Our vision for how Alaveteli’s theming should work was:

• Intuitive Front-end developers and designers should be able to follow and understand the templates without needing expert knowledge about Alaveteli’s inner-workings.
• Flexible Overriding Alaveteli’s core code should be easy, so a theme should use low-specificity, componentised code to enable this.
• Supportive Should a partner decide to only change a few colours, or embark on a large-scale redesign Alaveteli, the theming process should never get in the way.

How we did it

Using the tools we have

Alaveteli is built on Ruby on Rails, so our first goal was to make better use of Ruby on Rail’s template inheritance.

Firstly, we split all of the Sass files into logical components.

Each component has two associated Sass files, a layout.scss and a style.scss. layout.scss describes only layout of a component, e.g. the physical dimensions and position on a page. style.scss describes the styles, for example typefaces, colours, borders and other presentational properties.

Should a partner wish to totally redesign or replace a component, they can replace both files with their own. Alternatively they can just choose to replace one part of the component, for example keeping the layout, but replacing the styles.

Ensuring the lowest possible specificity

When customising Alaveteli we want to be sure that a partner never has to fight with the base theme to achieve their goals. The most important part of this is to ensure CSS styles are easy to override.

Firstly we removed all ID selector’s from Alaveteli’s stylesheets and replaced them with class selectors, giving us a good jumping off point as class selectors have much lower specificity than IDs. We then rewrote and refactored Alaveteli’s CSS using the Block Element Modifier methodology (BEM).

BEM helped us in two ways: it’s written in a way that makes CSS self-describing, for example the code snippet .header__navigation__list tells us that this list is a child of the navigation element and a grandchild of the header element.

As well as this, using a single class to define the styles for this element means that using BEM gives our styles the lowest possible specificity, so partners can override them with little resistance.

Using a settings partial

All of our theme’s styles use the variables defined in _settings.scss when referencing colours, typefaces, spacing, and even logo files so the bulk of Alaveteli’s customisation can be done in our base theme’s settings partial _settings.scss.

This allows partners to make simple changes which have a huge impact on the look and feel of the site. We’ve found that the large majority of our theme customisation can be done by just changing the variables in this file and it has sped up the theming process markedly.

Impact

We’ve quietly rolled out these updates to Alaveteli over the past 12 months and the impact of the changes has been encouraging.

Internally, we’ve found our theming projects are faster and more efficient. We conservatively estimate that it takes half the time to make a new theme than it used to.

Thanks to the self-documenting nature of BEM and the styles encapsulated in our settings partial, Alaveteli theming requires a lot less understanding of the platform’s inner workings. Our partners are able to be more self-sufficient and rarely require our intervention to assist with simple customisations.

Maintenance and support of our themes is greatly simplified, as the structure is consistent across projects, we’re able to roll out further changes and fixes in a more predictable way.
Overall, we’re really happy with how the changes worked out and the things we’ve learnt from this project we’ll be carrying into our others too, so look out for changes like across our work in the future.