As services age, as they’re iterated, built and rebuilt, and team members come and go, institutional memory fades and questions about why a service is the way it is become hard to answer. Context gets lost, research disappears and the design becomes opaque.

Keeping a design history makes it easy to know why a service is the way it is.

A design history is like a blog, with posts describing the development of new features, iterations of existing ones or findings from user research – anything that may be useful to return to later.

On the Becoming a teacher team, we’ve been using a design history to document the evolution of the Find postgraduate teacher training and Apply for teacher training services since they began in May 2018.

Our design history is a public record of our designs and it tells the story of what we’ve designed and why:

https://bat-design-history.netlify.app/

The value of documenting design

A design history looks forwards and backwards.

New posts show the team where the service is going. They highlight what will be researched or built next, and can draw attention to important design points.

Old posts tell us how we got here. With them we can:

• discover what we did and why
• re-evaluate decisions
• see how a feature has changed
• see how things tested in research
• give context to new team members
• see what didn’t work
• see things we tried but didn’t build
• see how things looked at significant milestones

By making the design history open we can share our designs and our reasoning behind them. Whether that’s with colleagues, other teams, the rest of government, or with service assessors. Make things open, it makes things better

Create your own design history

We’ve found keeping a design history to be incredibly useful and now we want to see other service teams benefit too. We’ve taken our design history and made it into a tool for other teams to use.

You can now use GOV.UK Design History to document and share your design decisions and create a permanent record of how your service has developed over time.

How our design history began

In 2018 we were struggling to document our designs.

We started by trying to upload screenshots to Confluence, but this was cumbersome. We tried versioning our prototypes, to keep old designs around on different URLs. But designs changed too frequently. The prototype could show us what, but not why. If designs were going to be documented it needed to be quick and easy or it would be seen as a chore.

We used the GOV.UK prototype kit to make the first design history and hosted it on Heroku. The kit made it easy to create pages, and we began by making posts for each feature, showing a list of screenshots alongside descriptions of what had changed and why.

With a page for each design we now had a public URL to share with the team, to put into Trello cards or pull requests. An example of an early post.

When it was clear these posts were useful we made creating them easier. We automated the process with scripts for taking screenshots, saving images to the right place, and generating a page with all the markup needed. Now we could focus on writing about the design rather than the task of recording it.

By using the GOV.UK design system for our posts we had an easy to use, readable and familiar platform for our design history. It felt right from the start.

As we researched our designs we recorded findings alongside screenshots, we began to link to research playbacks and video clips on Lookback (a tool for remote user research) – creating a direct link between a design and the source of a new finding.

Over time we could begin to show the old and new designs, and callout specific changes. We were evidencing and recording our design decisions as we went, and the design history entries began to tell our story.

Recording milestones and more

As the history grew, we used it to record more – like snapshots of the service at important milestones, such as at the launch of a public beta or our first publishing tool.

When prototyping a complex feature its logic can become hidden in code or only visible for particular user journeys. Where these rules and scenarios emerged, the design history became the natural place to describe them, and this made it easier for developers to build those features.

For example, in Apply for teacher training we ask candidates for their nationality. Our design history post describes asking for multiple nationalities. It explains how candidates can record multiple nationalities, what happens when 2 or 3 are recorded, how the design works without JavaScript and how we made it accessible.

Occasionally we needed to print designs – to show in research, to put on the wall or for group sessions. A post typically shows screenshots for a complete feature or user journey, printing those screenshots would be ideal. So we added print styles, meaning that each post can be printed, one screenshot (and title) per page.

We documented the information we ask users for, the emails we send users and the processes our team followed.

Making contributions easier

When the design team grew, more people needed to contribute.

To make it easy for anyone to contribute we switched from the prototype kit to Eleventy. Eleventy is a static site generator used for blogs – not unlike a design history, while the prototype kit is for prototyping government services.

Eleventy gave our posts structure – a title, description and date. It also meant we switched our posts from HTML (which was difficult for some team members to write), to markdown, which everyone understood.

Now designers, developers, content designers and user researchers are all contributing to the design history.

With Eleventy we added new features to make the design history easier to use: pagination, sorting of posts by date or category, related links and importantly – given the new volume of posts – search.

As of July 2020, we’re documenting 5 products with over 200 posts.

What next

We want more teams to keep an open and public design history. When we’re designing something new, and we’re looking to see how other service teams have solved that problem, we want to read about their designs, to evaluate them and to build on them.

We’ve created GOV.UK Design History to enable this – a repository with all the features, scripts and guides for getting started.

We’ll continue to add the features we need – like ways of documenting user needs and design hypotheses, integration with other tools like Trello, and more – but we hope that by opening up this tool to share with other teams, we’ll see new developments and ideas from outside our team.

Food mattered most

We buy more food and drink than anything else. Day to day it’s what produces most of our waste. And very little food comes without some form of plastic. Some fruit and vegetables, something freshly baked, eggs, some frozen items, tins and cans, jars of preserves, that’s about it.

Most things are in plastic – pre-made sandwiches, packets of cheese, pots of yoghurt, packs of meat, punnets of strawberries, bagged bread, anything processed, most desserts and most snacks.

About 5% of products are without plastic. Plastic is pervasive, even if it’s just the plastic window in a cardboard box or a thin shrink wrap. Walking around a shop looking for just one thing you can buy is a frustrating endeavour, more so with a crying toddler.

We were already doing the easy stuff

Before starting this challenge we were already buying lots of stuff without plastic:

• Milk delivered in glass bottles from Milk and more
• Fruit and vegetables delivered from Barcombe nurseries in a veg box
• Nuts, dried fruit, pasta and porridge refilled from Hisbe
• Sourdough bread from The Flour Pot
• Toilet rolls from Who Gives a Crap

This meant we’d already picked off the low hanging fruit, for most of our remaining plastic purchases there was no easy alternative; yoghurt in glass isn’t a thing you’ll find easily (we found it just as July ended), chocolate and biscuits are always wrapped, meat must be protected with a plastic tray and shrink wrap if it’s not on a meat counter. It was easier to simply stop buying these things than to find alternatives.

The benefits of Brighton

We live in Brighton, and very close to us we have a supermarket, an organic grocer, a local baker, a deli and a coffee shop. This made some things significantly easier, and this is partly how we made it through the month.

We only had to pop outside to buy sourdough. Small Batch coffee refilled our bags of coffee beans. The deli could slice chunks of cheese and put it in our pots, and they make a perfect pistachio cannoli with zero packaging. The grocer let us buy fruit and veg top-ups without plastic, and we ate so much melon.

And further afield we had access to shops like Hisbe, where we can refill pots with what we need, including pasta and cereal.

Cooking more and snacking less

As a side effect of buying less plastic we had more fresh fruit and more fresh vegetables. We made more smoothies and snacked on fruit. We cooked meals from scratch and ate more healthily. We ate our weight in eggs and bananas.

Our food wasn’t stuffed with preservatives. By not buying plastic we weren’t buying palm oil. We found ourselves with more locally produced things, supporting local sellers.

Less meat

We ate a lot less meat. Once a week we went to a shop with a meat counter and filled our containers – bacon, a pork joint, salmon – but prices are significantly higher. Meat became a luxury, and we mostly depended on whatever was in the freezer.

Spending more

Buying without plastic is a privilege. It’s the pricier goods that are plastic free.

Fresh sourdough costs three times more than an average loaf. Milk in glass costs more per pint. Fruit and vegetables cost more per item when not in plastic, they’re the bigger varieties, the tastier ones, the organic ones. It’s only expensive meat and fish out on the counters, the nice cuts. And at the deli it’s only fancy cheese to choose from.

Value ranges are always in plastic.

Frozen is the exception

Frozen food doesn’t depend on plastic to keep it fresh or to protect it from spoils. It’s escaped the trend for small plastic windows to show off the product – frozen food doesn’t look good. There’s more range in the frozen aisles for anyone avoiding plastic.

Frozen food was our go to when we needed something quick and easy.

This didn’t mean we could buy ice cream. And on the hottest July day on record we made our own alternative – milk and frozen bananas blitzed with chocolate and peanut butter. Better than anything we might have bought.

Empty bins

By steering away from plastic in our food purchases our waste bin became empty. We compost our food waste (and cardboard tainted by food) using a community composting scheme. Cardboard gets recycled.

After the first week there wasn’t much left to go in that landfill bin.

Buying lunch in London

I ditched Pret for the month. Almost everything in Pret comes with a little plastic window, and the sandwich boxes are lined with plastic too. I switched to Leon who provided plastic free packaging for their rice, burgers and chips, I made sure to bring my own cutlery, even if theirs was compostable – those forks need an industrial composter. The local market helped, burritos especially.

Non-food

We stopped buying things online. We couldn’t guarantee something would be plastic free. Plastic envelopes, bubble-wrap, random plastic bags. A cardboard box of canned soft drinks with a superfluous plastic wrapper from Ocado, or a book with too much plastic protection from Amazon, these were our scars. So we just said no. We bought on the high street and supported local traders. This meant we bought less.

Our existing shampoo and toothpaste survived the month in their plastic containers. We didn’t need to find alternatives for July. Plastic heads on our electric toothbrushes barely held out. We didn’t need any more toiletries, we already had floss in a reusable glass pot.

We used reusable nappies, and we already had reusable cloth wipes. Wet wipes are made of plastic and they don’t biodegrade, we already avoid them.

Behaviour changes

Because of this challenge we did other good things – we both found ourselves picking up and clearing rubbish on the streets a lot more. Brighton is by the sea and plastic on our roads has a bigger chance of ending up in the ocean.

We talked to people about our challenge, its difficulties but also the little solutions we’d found. We encouraged others to try something different. We observed just how much plastic other families were using, and noted how well we were already doing in cutting out throwaways.

What next?

It’s August now, and we’re relaxing our rules, ice cream and pizza are back. But once you’ve seen the plastic everywhere, once you’ve looked for it and tried to avoid it, it’s very hard to un-see. The more you look the more you see. We’ll continue to reduce and reuse, our net plastic use will no doubt be lower now.

This was also an extreme challenge – zero plastic is probably not the answer. Reusable plastic in moderation has its benefits.

We’ll try it again next year, with the hope that in a year’s time it’ll all be a littler easier.

At Government Digital Service, everything we build must be accessible. It’s one of our design principles, ‘This is for everyone‘:

Accessible design is good design. Everything we build should be as inclusive, legible and readable as possible. […] The people who most need our services are often the people who find them hardest to use. Let’s think about those people from the start.

Accessibility acceptance criteria are one of the tools we use to make sure our user interfaces are accessible.

What are accessibility acceptance criteria?

They are a list of conditions that a user interface must meet to be considered accessible. They help us raise awareness of access needs and maintain accessibility as we iterate. GDS has used acceptance criteria for years (for example, this 2015 Verify blogpost about acceptance criteria and in the 2014 GOV.UK style guidance), so formalising and expanding the accessibility-related acceptance criteria seemed logical. Be aware that accessibility acceptance criteria alone won’t make your service accessible – read more guidance on building an accessible service.

Raise awareness

Accessibility acceptance criteria raise awareness about what accessible means in a specific context. They’re more specific than general accessibility guidance, such as the Web Content Accessibility Guidelines (WCAG). By drafting the criteria upfront, we are forced to think about accessibility and the range of users from the start.

Maintain accessibility

Accessibility criteria also help us maintain accessibility as we iterate. Without them, it’s easy to introduce accessibility regressions when iterating on interfaces. Even when we know an interface has been built well, and that effort went into making it accessible – how do we make changes without breaking accessibility? What stops our new definition of accessibility from being incomplete or different to the original definition? Outlining accessibility issues in criteria helps us record the decisions that were made in earlier iterations and allows us to define the rules that keep something accessible.

Examples of accessibility acceptance criteria

Accessible autocomplete on GOV.UK

At GDS, we first used accessibility acceptance criteria when building the accessible autocomplete in January 2017. The team working on this (Theodor Vararu, Léonie Watson and Ed Horsford) defined the autocomplete accessibility criteria – the necessary behaviours that an autocomplete needs to meet to be usable by assistive technologies. The field with autocomplete must:

• be focusable with a keyboard
• indicate when it has keyboard focus
• inform the user that it is an editable field
• inform the user if there is a pre-filled value
• inform the user that autocomplete is available
• explain how to use autocomplete
• inform the user that content has been expanded
• inform the user when there are matches, or if there are no matches
• inform the user how many matches are currently available (optional)
• inform the user as the number of matches changes
• enable the user to navigate the available matches using touch or keyboard
• inform the user when a match is selected
• inform the user which number the currently selected match is - for example, 1 of 3 (optional)
• inform the user if a match is pre-selected
• enable the user to confirm the selected match
• inform the user when a match is confirmed
• return focus to the editable field when a selected match is confirmed

Translation component on GOV.UK

When we link to a translation of a GOV.UK page, we identify the following criteria:

The translation navigation links must identify the language of the link for correct screen reader pronunciation.

While this is true for all words that are in a different language, it is especially important to consider in the context of this component. Here there is a high risk of introducing an accessibility barrier.

Banner component on GOV.UK

On banners that place white text on a blue background, the criteria we use highlights the importance of contrast ratios:

The banner must have a text contrast ratio of at least 4.5:1 against the background colour to meet the WCAG AA guidelines.

While all text must have a sufficient contrast ratio, this component’s use of colour has an increased risk of introducing a barrier.

Writing accessibility acceptance criteria

These are the guidelines we use for writing accessibility acceptance criteria.

Start with accessibility needs

Identify where there is a high risk of introducing an accessibility barrier and include criteria that prevent it. If similar things already exist, review them and test them with users who have access needs. For example, the original criteria for the accessible autocomplete were derived from tests made by Theodor Vararu (a frontend developer in the autocomplete component team) on existing autocomplete libraries. Often, the hard work of defining what accessible means has been documented in guidelines like WCAG. Extract rules that are specific to what you’re building and link back to the guidelines to give context. Consider which rules are most easily broken and give them prominence.

Don’t be too generic

Criteria are useful if they are specific and testable. When we began writing accessibility acceptance criteria for components, we had difficulty knowing what to include. For example, with components that contain links, should the criteria list everything that makes a link accessible? How much of this becomes a reproduction of existing guidelines? For the translation component, it was helpful to create a shared definition of an accessible link that we could link to. This avoided diluting the criteria while giving us a place to record more generic decisions.

Don’t define the solution

Like acceptance criteria in user stories, accessibility acceptance criteria describe an outcome rather than the solution. The criteria should give room for interpretation and allow designers and developers to make improvements over time. Ideally, if technology or designs change, the criteria will still apply. For example, in the banner component criteria, we state the required contrast ratio, but we do not limit the design with implementation specifics such as font size or colour.

Iterate criteria

As something is built and tested, continue to refine your criteria as you find missing needs. When accessibility bugs are found – a browser bug, a screen reader quirk, new technology misbehaving – add further criteria and treat them like a failing unit test.

What next?

Writing accessibility acceptance criteria for user interfaces on GOV.UK is a new practice which we will continue to refine and build process around. We’ll include accessibility acceptance criteria in our component guides and developer documentation (see the contents list component for an example). We’re also keen to hear from others who’ve used accessibility acceptance criteria (or something similar), and what they’ve found – please leave a comment.

• Avoid glitter. Most glitter is made from plastic, it’s microplastic which increases the likelihood it will be eaten by small animals.
• Avoid fireworks on New Year’s Eve, they kill wild animals
• Just don’t bother with Christmas crackers, they’re expensive and go straight to landfill

Gifts

When wrapping gifts:

• don’t buy new wrapping paper, especially paper wrapped in single use plastic
• reuse wrapping paper you already have (cut out bits of old tape)
• reuse that brown packing paper Amazon stuffs into its packages
• use brown paper
• don’t buy gift bags, save and reuse all gift bags you’re given
• use string rather than plastic tape, then reuse the string, use paper tape as an alternative
• don’t buy gift tags, especially if wrapped in plastic, make tags from old Christmas cards

When giving and opening gifts on different days, keep the wrapping from one day and reuse on later gifts another day.

Give:

• experiences rather than things
• your time
• things you’ve made
• things you already have that someone else might want more
• digital rather than physical media
• things that aren’t made from plastic
• to charity

Ask for:

• gifts that don’t contain plastics or synthetics
• responsible gifts
• donations to charities you support

Christmas cards

Every part of a Christmas card can be reused:

• reuse envelopes as scrap paper, recycle after reuse
• donate used stamps to the RSPB
• split old cards in two, make the half with the design a gift tag for next year, use the back for scrap paper and once used recycle

Buy cards that:

• are made from recycled material
• don’t contain glitter or plastics
• don’t come in a plastic box
• give profits to charity

Plan ahead and buy your Christmas cards cheap in the post-Christmas sales. I don’t know what large shops do with any Christmas stuff they can’t shift, but it can’t be good.

What you eat at Christmas

• Buy locally
• Don’t buy too much, it’s ok to indulge but make sure you aren’t wasting food
• Avoid food wrapped in plastic
• Don’t buy individually wrapped chocolates
• Use all your leftovers – fry up veg, cold turkey sandwiches, and so on
• Don’t tip fat down the drains, keep for future roast vegetables and gravy
• Use turkey bones and vegetable peelings (if you peeled) for stock
• Compost food waste
• Buy late and purchase discounted food that’s destined for landfill (this year our local co-op reduced £14 lobsters down to £3.50, so we bought 4 and ate them on boxing day)

“The road will never swallow you. The river of your destiny will always overcome evil. May you understand your fate. Suffering will never destroy you, but will make you stronger. Success will never confuse you or scatter your spirit, but will make you fly higher into the good sunlight. Your life will always surprise you.”

“What is interesting and important happens mostly in secret, in places where there is no power. Nothing much of lasting value ever happens at the head table, held together by a familiar rhetoric. Those who already have power continue to glide along the familiar rut they have made for themselves.”

https://www.goodreads.com/book/show/11076177-the-cat-s-table

Techniques that people use to win their arguments and how to identify them.
Hard to know how to attack an argument if you don’t know which part is wrong.

• Find the weak points
• Problem at foundation of argument

Faulty justifications, simplifications used over and over.

Fallacies

Argument from consequences

• Argues how true or false something is based on whether they like the consequences of if that thing were true
• If god doesn’t exist, there’s no moral accountability, therefore I believe god exists. ‘I believe that god exists, because if it doesn’t, that’s just not a world I want to live in’
• Just because someone wants it to be true has no connection with whether it is true
• If X then Y will happen, Y is a good outcome for me, therefore X must be true
• Finding fallacy tricky
• Sometimes an appropriate argument - eg appealing to consequences. Difference: Proposition for making things better rather than what we should believe is true. Consider politician campaigning for change.

Affirming the consequent

• Just because you know that if something happened a specific consequence would happen, and you live in a world where that consequence is a reality, you can’t just assume that that one thing that could have caused it happened
• If cashier won lottery, they would be happy. You go to shop and see they are happy, therefore they won the lottery
• Other explanations for why
• Wrong to use consequence to confirm antecedent
• If someone was going to be a good president they would have seen economic downturn coming. Trump saw it coming, therefore he would make a good president. Argument doesn’t prove good or bad.
• If god existed we would be able to see unparalleled beauty in nature, it’s all around us, therefore god exists.

Appeal to ignorance

• We can assume that something is true simply because there is no evidence that it is not true.
• No evidence Bigfoot doesn’t exist. Therefore Bigfoot exists
• Cloaked in clever ways
• Bush when running for president. Dan Rather suggesting Bush not honourable in National Guard. Bush response: using forged documents. Now: to dismiss claims, prove documents weren’t forged - but how? By the time you do argument gone off rails.
• Hide behind stage of gathering definitive evidence. Use as shield. Know that process will be impossible or exhausting.
• Stalemate often
• Personal incredulity variant: believe because not disproven yet, convenient way to believe what you believe without questioning it.
• Because it’s hard to understand they assume it must not be true.
• What someone feels should be possible is baseless.
• Judging what’s possible in a field of expertise they have no knowledge of.

Slippery slope fallacy

• Make case that a position is bad because acceptance of it would bring about a sequence of events that would be horrible
• Sidestep discussion, conclude that this thing you’re discussing will lead to this horrible outcome, then ask the person you’re arguing with to defend the horrible outcome

Straw man fallacy

• When winning
• Takes argument and paints simplified version of argument for easy target to attack
• I believe in God, what you believe there’s some old guy with a beard on the sky watching over all of us?
• I think we shouldn’t spend 600bn on military spending. Straw man back: I can’t believe you’d want to leave the country defenceless.
• Mischaracterising an idea, making a worse argument, easier to refute, easier than understanding original argument

Ad hominem argument

• Attack personally in attempt to discredit source of information
• When winning
• I don’t think it’s a good idea to throw cats off buildings - oh yeah, coming from someone who’s never had a cat before?
• Knee jerk response
• Diversion
• Discredit source then don’t have to look at beliefs honestly
• Pretend words I had said were said by someone you respect

False equivalence

• Common in media
• Goal to use one or two attributes to use to pretend as though both things are the same
• Both cats and dogs fluffy, so they are the same
• Some scientists have done experiments to say humans are causing climate change, some say they aren’t. Guess it’s a stalemate.
• Just because both sides have done studies does not mean they are both done legimitiately, honestly, number of studies, sample sizes

Appeal to bandwagon

• Because majority believe in something then it must be true
• Commercials
• 100s of people happy because they use X
• Millions used to believe earth was flat. Millions now believe it’s not flat, that’s not what makes it true.

• Be kind
• Check your privilege
• Hold loose convictions
• Avoid absolutes
• Make it hard to do things badly
• Be lenient in what you accept

• Birdsong that varies around the world and at night
• Seeing the V-shape of birds flying over at dawn
• Learning about the cold, and keeping a torch for warmth
• Accidentally catching fish with a bomb
• Chopping down a tree to make a bridge
• Gliding and climbing
• Riding my first horse
• Seeing my first fox
• Bumping a bear in the forest
• Picking up a skeleton head and kicking it off a cliff
• Seeing a double rainbow
• Seeing the northern lights
• Chasing a falling star
• Stumbling on my first dragon
• Trying to photograph lightning
• Standing in the rain
• Completing a shrine in a way that’s different to what’s intended
• Trees that are different from each other
• Finding durian
• Being chased by wolves on a mountain for the first time
• Pulling out the master sword
• Stopping time and attacking an enemy
• Using Daruk’s protection to kill guardians
• Posing at the top of Hyrule Castle’s spire
• Watching Link glide down as Ganon rises from the floor for the final battle
• A flash of the triforce
• Silent princess flower at the end

#9 The Buddha

• Life of Buddha
• How Buddha came to four noble truths

Four noble truths

1. The nature of suffering

• Suffering is universal
• Dissatisfaction is the default state of the human brain
• Satisfaction, or happiness, leaves as often as it comes
• No matter what: It eventually fades (eg buying your dream car)
• No matter how good something is, eventually it just becomes normal
• You no longer fully appreciate what you have

2. The cause of suffering

• Desire (created by mind in different ways)
• Attachment, aversion or ignorance
• Attachment
  • See something they want, assume having that thing makes them happy
  • Exalt the good properties, ignore bad things
• Aversion
  • Magnifies problems into things bigger than they are
  • Agonises over things they have no control over
  • Cut in line example, some people fuming, anger to be expected, “if only I didn’t have to deal with…”
  • Someone from a different set of experiences having same things happen to them may not feel slighted
  • Expectations: Expected to be treated in a certain way. Why is not meeting those personal expectations bad.
• Ignorance
  • From attachment and aversion – your individual happiness depends on and is controlled by the world around you
  • “If only X hadn’t happened…”
  • No good things or bad things, just things (examples of bad things leading to good things)
  • Things, people, places, situations – none have inherent characteristics, we just think they do
• Ineffective ways of pursuing happiness, destined to fail

3. How suffering can be eliminated

• Suffering can be ended by eliminating desire
• Desire comes from selfishness
• Delusion that you exist separately from everyone else
• We are all part of a giant internal structure of existence that’s interconnected
• Ego
• Be mindful of what’s productive

4. The path to remove suffering altogether

• Get rid of your ego
• Roadmap to Nirvana - the 8-fold path, perfect it to achieve enlightenment
• Morality: Right speech, right action, right livelihood
• Meditation: Right effort, right mindfulness, right concentration
• Wisdom: Right understanding, right resolve
• Interpretations vary enormously
• Easier said than done

Buddhism

• Mental gymnastics
• No God beholden to
• Fate in own hands
• Buddha significance is example of reaching Nirvana, something to emulate
• Encouraged discourse and discussion
• Meditation and mindfulness
• Ego: A person always in your face, yammering on about “you!”, from birth to death, on and on – non-stop internal chatter.
  • Try to think about one thing
  • Surprising how easy to fail
• Mindfulness is about monitoring thoughts to determine if productive, eventually decrease bad

October 17 (page 110)

“This is closer to my own idea of freedom, the possibility and prospect of ‘free life’, travelling light without clinging or despising, in calm acceptance of everything that comes; free because without defences, free not in an adolescent way, with no restraints, but in a sense of the Tibetan Buddhist’s ‘crazy wisdom’…”

November 11 (page 213)

“We have no news of modern times since late September, and will have none until December, and gradually my mind has cleared itself, and wind and sun pour through my head, as through a bell. Though we talk little here, I am never lonely; I am returned into myself.”

November 26 (page 276)

On Tukten:

“… he rarely speaks, except when spoken to, and never seems to speak too much; without obtruding, he becomes the centre of each situation, so naturally does he belong where the moment finds him.”

https://www.goodreads.com/book/show/764165.The_Snow_Leopard

We have sought to change our lifestyle to a greener one as a first step; one that reduces emissions, one that is sustainable, one that is ecological. This has been rewarding, but we have also been dismayed by how difficult it can be.

What we consume

Something that gives an immediate benefit is a switch to a low-emissions diet. Choosing food that takes less energy to produce, and choosing items that don’t need to travel as far to get to us.

This means we’re:

• eating less meat, especially beef
• buying locally (Brighton makes that easy)
• buying leftover food from Brighton’s Junk Food Project, food that is otherwise destined for waste
• buying locally made bakery items without palm oil
• trying out more sustainable loo roll

These are positive changes, but it’s difficult to measure their effectiveness.

Emissions-based decisions are hard

Making emissions-based decisions on food is difficult. We ask questions like: Does beef produced locally in the UK lead to fewer emissions than imported pork? Do shellfish from Thailand hurt the environment as much as farmed salmon from Scotland? What affect does packaging have? Crucially, how much difference is there between the environmental impact of one thing and another thing?

Multiply these questions for everything and the plan is soon abandoned. I can make assumptions, but I don’t know enough about the food industry to validate them. There is no clear indicator displaying the emissions or environmental impact of a product. Trying to eliminate unsustainable palm oil from our diet was impossible. Trying to determine what kind of milk – dairy or any of the alternatives – is most ecological is a multi-variate minefield.

It’s hard to positively change behaviour without having easily available data to inform your decisions.

How do we make ecology based buying decisions normal?

Less waste

We’re throwing out less, re-using more and recycling whatever we can. That old “reduce, reuse and recycle”, with a bit of fixing stuff too.

This means we’re:

• using community composting services, our waste doesn’t travel far
• using less water
• preferring goods without packaging
• re-filling containers (cleaning products, food, etc)
• using re-usable cups for take-away coffee
• using our own bags
• reusing wrapping paper by replacing tape with string
• reusing cards and envelopes as scrap paper for notes
• making regular shopping trips (walking) to buy only what we need
• recycling plastic, cardboard, metal and glass
• fixing old clothes
• reducing junk mail by registering with Royal Mail to cancel all unaddressed mail

More composting

We want to compost more. Local council waste services don’t take compost. We’ve joined local composting initiatives but these don’t take all food waste; cooked food, carbohydrates, meat and sugary items aren’t composted as they attract rodents – they still end up in landfill. Rats.

Joining a community scheme takes effort. In central London where I work it’s impossible to compost food waste.

How do we make composting the default?

Green energy

We’re using measurably less energy by being vigilant, and we get all our electricity from a 100% renewable source.

Electric cars need charging

My wife and I both have long commutes, upwards of an hour each way (by train, and by car). We’re reducing emissions by working from home more often and driving more efficiently (slower, less far).

We want to switch to an electric car, but we’ll have nowhere to charge it. We can use on-road parking or our flat’s private car park, neither have chargers. There are subsidies for installing car chargers, but we have nowhere to put one. We’re pursuing putting chargers in our private car park with the local committee, but aren’t hopeful. I can’t imagine how Brighton will make the switch from petrol cars to electric ones without significant investment in communal chargers.

How do we make it easy for anyone to charge their electric car?

Protecting what we love

Going green isn’t just about living sustainably, it’s also about protecting green spaces, wildlife habitats and our wilderness. We’ve started regular donations to organisations that do that hard work:

• The RSPB
• National Trust
• Wild Wetlands Trust (WWT)
• Sussex Wildlife Trust
• Save the frogs

Learning about climate change

By changing our own lives we’ve discovered many things that make it difficult to go green. There’s a lot of difficult to answer questions.

To find ways to answer these questions, and to get more context I’ve started some focused study on climate change. I’m beginning with:

• What’s a technologist do about climate change?
• Top 10 books on the climate change movement
• “This changes everything” by Naomi Klein

GOV.UK has been focused on rebuilding publishing tools, aiming to consolidate them into a coherent platform. Applications were built in isolation, for specific user needs, eg travel advice. This led to many similar applications doing the same thing differently. On the frontend it meant similar but slightly different pages.

The publishing platform solves this problem with a common API for publishing and rendering content across all applications. We write functionality once and use it everywhere.

GOV.UK publishing tools are typically in two halves: a backend app where content designers create and edit content, and a frontend app which renders content for the public. We have about 20 frontend apps, which we are consolidating.

Whitehall

Whitehall is the application responsible for publishing and rendering all content under the /government path. It’s a monolith and an exception to the rule. It’s responsible for things like the budget and the national curriculum. It handles formats like consultations, statistics, all department news, speeches, policies, and a whole lot more. It was built quickly to meet many user needs and has organically grown to become unwieldy.

government-frontend

I’ve been in the “Core formats” team, we’re responsible for migrating all of Whitehall’s formats to the publishing platform. When migrated, content written in Whitehall is sent to the publishing platform, from there a separate frontend app consumes a “content item” (a JSON representation of the content), and renders it. That application is government-frontend.

Format by format we’ve been moving the frontend out of Whitehall and into government-frontend.

Defining a format

What is sent to and retrieved from the publishing platform is defined by JSON content schemas. For a format, eg speeches, we define attributes specific to speeches – like where the speech was given, when it was given and the body of the speech.

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "additionalProperties": false,
    "required": [
      "body",
      "delivered_on"
    ],
  "properties": {
    "body": {
      "type": "string"
    },
    "location": {
      "type": "string"
    },
    "delivered_on": {
      "type": "string",
      "format": "date-time"
    },
    …
  }
}

We also define other content types the format is connected to. The speech is given by a person or speaker, it might be about a policy. These connections are called links.

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "speaker": {
      "description": "A speaker that has a GOV.UK profile",
      "$ref": "#/definitions/guid_list",
      "maxItems": 1
    },
    "policies": {
      "$ref": "#/definitions/guid_list"
    },
    …
  }
}

Using examples to build the frontend

Using the schema we can build example content items. These samples of JSON are based on live content and are representative of what the frontend application will consume when the format is migrated. This example of a speech is based on a speech about gender imbalance in the nuclear industry.

Using a set of examples the frontend for a format can be built. This pull request allows government-frontend to render speeches. The pull request is comprised of:

• a presenter for handling the JSON content item of a speech
• a template to render the speech
• a stylesheet for speech specific styles
• a unit test for the presenter
• an integration test for the presenter and view

A rendered example

Finishing migration

Migration continues on the backend. Whitehall is updated to send content to the publishing platform. This can be a complex process depending on the intricacy of the format. When complete, all content for a given format is published through the new pipeline and rendered by government-frontend.

The therapeutic last step is to delete the old template, styles and tests from Whitehall. For example this pull request deleting the frontend for policy groups.

A combination of an established module pattern, headings with dynamic IDs, content on a specific topic and the quirky way that browsers handle IDs on elements created an obscure bug.

The bug manifested in a way that broke other things, it started as a report about a contents link overlapping some content. The console showed the unhelpful error:

Uncaught TypeError: undefined is not a function

Exports and modules

CommonJS uses a global exports variable to export properties from a module. A pattern in frontend libraries is to check for the presence of exports to see if the library, in its current context, should behave as a module.

Here’s what you’ll usually see:

typeof exports !== 'undefined' ? exports : SomeLibrary

At GOV.UK we use Hogan for javascript templating. At the bottom of the Hogan library you’ll find a similar line:

(typeof exports !== 'undefined' ? exports : Hogan);

Element IDs

Browsers have a quirky and little known behaviour when it comes to element IDs. The window object must have a property key with the value element, if there is exactly one DOM element with the ID key.

Essentially, elements on a page with a unique ID create a global variable.

With this markup:

<h2 id="heading">Heading</h2>

You can access the element with the following JS:

// Each returns the element
window['heading']
window.heading
heading

Internet Explorer started it and now it’s a standard:

• WHATWG
• W3C

There’s a lot of bad things about this, Bob Ince on Stack Overflow gives a good summary of the mess you could find yourself in.

IDs on page headings

Well structured content gets broken down into parts, each with their own heading. Linking to part of a document is useful and the common approach is to link to an ID using a fragment identifier.

To make this easy publishing tools often generate IDs on headings, based on the heading text. GOV.UK does it, so too does this blog. The heading above, “IDs on page headings” has the generated ID: IDs_on_page_headings, this is a link to it.

When you’re government it’s likely you’ll create an article about imports and exports. Here’s one: A guide for international post users

Putting it all together

On pages with an exports section we see:

<h2 id="exports">Exports</h2>

Browsers take the ID and create window.exports. Now when we call the Hogan library code, the check for exports gives a false positive. Hogan gets passed an HTML element instead of an empty object, and fails to start properly. Subsequent calls to new Hogan.Template then fail.

var Hogan = {};

(function(Hogan) {
  // The value of Hogan at this point is the HTML element
  // <h2 id="exports">Exports</h2>

  // Hogan code
  …
})(typeof exports !== 'undefined' ? exports : Hogan);

The hot fix

We aren’t using the CommonJS module pattern. Removing the exports logic fixed the bug. Here’s the pull request: Remove typeof exports check in Hogan libraries.

-})(typeof exports !== 'undefined' ? exports : Hogan);
+})(Hogan);

This needs to be fixed upstream, and the use of this exports pattern re-considered. I’ve opened an issue on the Hogan repository.

Tools all used Bootstrap, which provided patterns and styles for forms, dropdowns, menus, navigation and buttons. Admin user interfaces could be built quickly. But there are many different ways to use Bootstrap. Each tool was doing the same thing, but slightly differently.

Documenting patterns

When I began working on another admin tool, transition, I created the first admin style guide, and began to document the patterns used in building the app:

Document existing transition styles, how transition uses bootstrap, where it diverges and where there are custom styles. Includes grid, body copy, visited links, buttons, pagination and breadcrumbs patterns

It didn’t recreate Bootstrap’s own reference, instead it gave rules on how to use Bootstrap. This led to consistency within the application. For example, all tables would be table table-bordered with a custom table-header class applied to the column headings.

It also provided ways to document enhancements to Bootstrap, such as form helper classes for restricting input fields to standard widths.

Sharing across tools

When I switched from the transition team to the publishing tools team, I reached for the same toolkit on different apps. Patterns created for transition that were tested and validated with user research would be useful.

I was working across:

• publisher
• whitehall
• panopticon
• imminence
• sign on
• maslow
• travel advice publisher

Each application is an admin tool with its own purpose. Each looked roughly the same, each used Bootstrap, but none were sharing styles, patterns or behaviour. It wasn’t easy to add a filter to a table in both publisher and panopticon. Tables in imminence looked different to those in maslow.

All apps were built in Rails. A ruby gem would allow code to be shared across apps.

govuk_admin_template

Cue the govuk_admin_template gem. It began as a port of the patterns, styles, javascript and documentation from Transition.

The gem provides (via a Rails engine):

• jQuery and Bootstrap 3 with HTML5 and respond.js shims needed for IE8 and below
• An admin layout with header and footer
• A module instantiation pattern for javascript (loosely based on this blog post)
• A set of useful javascript modules
• Admin design patterns available from /style-guide
• CSS helpers and Sass variables for the admin theme
• GOV.UK user friendly date formats
• Google Analytics tracking

Each application was upgraded to Bootstrap 3 and switched to using the gem (that wasn’t always trivial).

Now they all use the same base layout, have the same Sass toolkit, follow the same Bootstrap rules and have access to the same set of features, like table filters and simple toggles.

It is now easier for all applications to look and behave consistently.

Government Digital Service

I’ve been contracting with the UK’s Government Digital Service (GDS) since September 2013, in that time all of the code I’ve written has been publicly visible on Github. GDS teams watch repositories that interest or affect them, and they’re notified by email when there are pull requests, comments, issues etc (there’s a lot of repositories).

Defining ‘prototype’

Prototype is an overloaded term, it could mean sketches on paper, an investigation into a technical solution, a way of translating and trying out designs. In this post I’m referring to designing and iterating directly within code, without any secondary design process (eg no high fidelity design developed in an image editor), save perhaps some early sketches.

Prototype code is throwaway, they are built quickly to give a realistic impression of the final product. No code from any prototype should make it onto a live website, at least not without considerable review and revision.

Building a design

My prototypes begin life as a branch, forked from master — all prototype branches are prefixed with prototype- to avoid confusion. This is a label: don’t critique this code. The branch will never be merged. From here I have a fully functional and recently released version of the application which I can begin modifying. That’s a good start.

As I begin to make design changes (using CSS, HTML, back-end code when necessary), at appropriate points I commit my work — as you would when developing a feature. The commit message describes the design changes up to that point, and these commits are regularly pushed to Github.

Importantly, I follow up a commit with a comment and screenshots which show the thing. Github has made adding screenshots really easy, just drag-and-drop them to the comment field. The comment will often include details of what the change is meant to address, what might be wrong with this approach, questions, perhaps some prompts for discussion. For example, a commit detailing changes to filters, and another with some debate surrounding an import process.

These comments and their images are then emailed to everyone watching the repository. The emails indicate that things will be changing, and they illustrate the design progress so far. They trigger important and welcomed discussions that influence the direction of a design at a stage when it’s most constructive, long before building has begun.

Life after prototype

At the end, the stages of the design prototype have been documented. Commit logs (which make it easy to step through design iterations), reasons for design changes, screenshots and discussions — they’re all easily accessible and linkable. So they’re linked to from user stories, pull requests and commits, and none of that vital design context gets lost in translation.

Clean repositories

There is a minor problem with this approach. Many developers, myself included, like to cleanup old branches. When should you delete a prototype branch? What happens to links to those Github pages? That’s a problem I haven’t dealt with yet.

No link left behind

A principle of transition is no link left behind, as Sir Tim Berners-Lee explains: cool URLs don’t change. Paul Downey says:

URLs - links and Web addresses - are the ‘strands’ in the Web metaphor. When URLs change, the strands break.

All government content is moving to GOV.UK, the old sites are being retired. That’s the potential for a lot of broken links. Across 800 websites there are over 1 million unique URLs. Government has lots of links in the wild; on websites, but also in letters, on mugs, in ads and on TV. Users will continue to click and type these URLs, expecting to reach the content they need. Those old URLs must continue to meet that need. Government needed a way to manage these URLs.

Managing mappings with the transition tool

Every old URL has a mapping from old to new. These are managed in a rails app named Transition.

An old URL can:

• be redirected to a GOV.UK page
• be archived

Redirects (301)

Redirects are served with a 301 status code, a permanent redirect. For example, this page on the old Environment Agency was for checking your flood risk:

http://www.environment-agency.gov.uk/homeandleisure/floods/31644.aspx

It redirects to the equivalent content on GOV.UK:

https://www.gov.uk/check-flood-risk

Archives (410)

Not all roads lead to GOV.UK. Archives are for content that doesn’t meet a user need. Content without a need isn’t transitioned to GOV.UK. These old URLs display a notice and a link to a version of the page on the National Archives.

For example this page about the old DFID website’s cookie policy is archived, with a link to the archived version:

http://www.dfid.gov.uk/about-dfid/privacy-and-cookies

They’re served with a 410 status code. 410 means “Gone”:

The requested resource is no longer available at the server and no forwarding address is known. This condition is expected to be considered permanent.

Research and design

From the first prototype to the live application we conducted frequent user research sessions with our government users. Research asked users to perform tasks and probed their understanding of the process. These sessions led to iterative changes in the application, changes that were tested again with further research, either validating our patterns or challenging our assumptions.

Words not status codes

An early version of the application used 410, 404 and 301 for mappings. Research showed that users didn’t know what these codes meant, or worse, interpreted them wrongly. Rather than explaining the codes we replaced references to them with “Redirect” and “Archive”, terms users knew already, titling them with “Type” rather than code.

Handling many paths

Managing thousands of mappings is a daunting task. Editing them one by one was very obviously not ideal, creating bulk editing tools was a big deal.

Research highlighted that:

• many similar paths get redirected to the same GOV.UK page
• many similar paths get archived
• sites without a clear URL structure were harder to manage
  • users needed to group paths to manage them
  • groups used for paths would be dependent on website and organisation
• it was hard to know which paths were most important
• it was unclear which paths had already been checked or edited

Editing multiple mappings

On a list of mappings we added a way of selecting a range (one by one, or by shift-clicking a range) using a familiar pattern found in web email clients. That set of mappings could then be redirected, archived or tagged. It tested well.

Grouping mappings

To group paths we added filtering and tagging. Organisations were free to create groups of mappings with whatever tags they liked. Tag autocomplete encouraged users to select tags their organisation had already used while tags themselves were hyphenated and lowercased to eliminate a lot of inadvertent variation. This follows my design principle of “Making it hard to do things badly”.

What paths are most important

To indicate which paths had most importance we added hit counts, in a column that could be sorted.

Which paths were ready?

The default mapping was “Archive”, but it wasn’t clear whether a mapping was set to archive through choice or by default. A third pseudo-state was introduced, it behaved exactly like an archive but had the type “Unresolved”, this made it clear which URLs were being archived by default or still required a decision.

Fixing mappings

After transition it’s important to check on the performance of mappings. It’s possible that mappings were missed (they were imported from web logs), or mistakes were made – an archive with a real user need.

The transition application provides analytics for all old websites, showing which URLs are being hit and what proportion of them are archives, redirects or errors; an error being a 404 page that has no corresponding mapping.

David Mann outlined the process on the transition blog. High traffic to redirects is what’s expected, but many errors would suggest many missing mappings, and high traffic to an archive might indicate a user need that’s been missed.

Based on research findings, we made it easy to:

• create a mapping from an error
• edit any mapping from analytics
• know whether changes had already been made to fix a mapping

Progressive enhancement is important, and Last.fm remains a traditional HTML website with full page reloads. Using layers of unobtrusive JavaScript we build up functionality, not because JavaScript is sometimes disabled (that’s a rarity, even amongst screen reader users), but because broken JavaScript happens.

We use RequireJS for dependency management, Jasmine for testing, and jQuery. Our framework is light, and is founded on a simple instantiation pattern: modules are marked up using data attributes, anything with a data-require attribute is deemed to be a module. On page load, our app finds these modules in the DOM, ‘requires’ them and their dependencies, instantiates them and starts them. (A concatenated minified build file means we don’t make an HTTP request for each file.)

On creation each module is passed an instance of the app, from which the module can communicate upwards and outwards, as well as an element, the bounding box of the module, as defined by the position of the data attribute.

This markup:

<div data-require="path/to/module">
  …
</div>

Instantiates:

define(['some-dependency'], function(someDependency) {
  var MODULE = function(app, $el) {
  this.start = function() {
            …
        }
        …
    };
    return MODULE;
});

Looking at our legacy code this deals with three of the serious problems we’d faced: Knowing what JavaScript files are affected or used by others; providing a simple means to get a module up and running without resorting to inline JavaScript; and naturally limiting the module to operate within its bounds.

Configuration is commonly provided via further data attributes. Examples might be an ajax end point with data-url, or perhaps a Mustache template with data-template, etc.

<div
  data-require="module"
  data-url="path/to/endpoint"
  data-template="path/to/template">
  …
</div>

Separation of concerns

JavaScript modules define behaviour, behaviour that should be abstracted and distinct from presentation and semantics, eg. a disclosure, a toggle, or a drop down menu. Whether it’s an image, arbitrary text or a heading that toggles something, it shouldn’t matter — the module is given a set of interaction hooks and applies its behavioural rules.

We use classes to provide these hooks. The problem with using classes is the risk that those same classes will be used to define styles; this tightly couples presentation and behaviour. To avoid this all JavaScript hooks are prefixed with js-.

Here’s an example of a simple disclose module:

<div data-require="disclose">
  <p class="js-hide-on-disclose">
    Some preview that gets hidden.
  </p>
  <a href="/details" class="js-disclose">
    Show details
  </a>
  <div class="hide js-disclosed">
    Details to be revealed.
  </div>
</div>

define(function() {

  var Disclose = function(app, $el) {

    var that = this;

    that.start = function() {
      $el.on('click', '.js-disclose', disclose);
    };

    that.stop = function() {
      $el.off('click');
    };

    function disclose(event) {
      event.preventDefault();

      $el.find('.js-disclosed').removeClass('hide');
      $el.find('.js-disclose, .js-hide-on-disclose').hide();

      // Analytics tracking
      app.track('DisclosureOpened');

      that.stop();
    };
  }

  return Disclose;
});

App interface

The app acts as a tool belt for many of the common abstractions. All AJAX requests go through either app.get() or app.post(). There’s also a common event mediator, accessed through app.publish(), app.subscribe() and app.unsubscribe().

Keeping it simple

We’ve purposefully kept the code small. We do this by only building the features we need. For instance, until very recently we didn’t need a general purpose unsubscribe method, so we didn’t build one.