Should content be hardcoded or externalised?

(I published this blogpost originally on the Home Office Digital blog. It is archived here.)

Content design is informed by user research findings. With all government services this is critical, as it’s the user that needs to carry out certain tasks to reach a successful outcome – for example provide their date of birth or vehicle registration details.

How the content designer then gets the carefully crafted words into the service can be a challenge, and there’s more than one solution. Options can include using content management systems, such as, Drupal and WordPress, or working with simple text files.

Each solution has its pros and cons. And every time we start a new project we need to ask the question ‘how will we do the content?’

One of the first considerations should be whether the content lives within the code or is ‘externalised’. This decision should be made as early as possible in any new project.

The concept: externalising content

Externalising content means bringing the content out of the code into a separate content file.

It involves replacing the content with a ‘token’, which is entered into the code. That token represents the correct words, which are stored in a separate content file.

The idea of externalising content isn’t particularly special or new. It’s been done many times before and there are even standards and file formats for it.

When the website is viewed by a user, those tokens are replaced by the words written by the content designer in the content file. This happens invisibly to the user.

In terms of implementation, there are many ways to externalise content. On a previous project we used YAML files to store the content. This allowed content designers and user researchers to work together, change content and test quickly.

An example of what an externalised content file looks like. This example shows both Arabic and English content. A content designer can change content in this file.
An example of what an externalised content file looks like. This example shows both Arabic and English content. A content designer can change content in this file.

How does externalising the content affect me?

This will affect all members of agile software development teams in different ways.

How does externalising content affect a developer?

If you’re a developer at some point you’ve probably been asked to copy and paste content into your code. Depending on complexity, this takes time away from what you’re best at: writing code.

Every time content changes, you spend time copying and pasting. You may also have to rewrite your acceptance tests for continuous integration.

Externalising content lets you write your acceptance tests once and reduces the amount of changes needed to those tests.

How does externalising content affect a content designer?

If you’re a content designer, you want to write content and test it with users as often as possible.

Without a proper CMS you have no interface letting you easily change the content meaning you may have to rely on a developer to find time to change it for you.

Handing responsibility for content changes to someone whose primary focus is not the same as yours can be frustrating. And it doesn’t give you the flexibility of writing, testing and iterating content when you want.

Externalising the content allows you to change the content as you see fit without needing a developer to stop what they are doing.

How does externalising content affect a user researcher?

Content changes are as critical as user interface changes. Like content designers, you have to badger developers to get new content to test with users. Everything moves a bit slower. Working with the content designer who has control over the content means the user researchers work can progress at a faster pace.

What we’re proposing in Home Office Digital

Some of the more complex government services need to support multiple languages, or address multiple people, making the content requirements more challenging.

For example, does the content need to:

  • refer to the user in 1st person, or 3rd person?
  • support multiple languages?
  • be presented in more than one language on the same page?

These needs should be explored in the discovery phase of the project with conversations between content designers, user researchers, developers and designers to determine whether externalising the content would be appropriate for the service.

If it is appropriate, and since there is often no graphical CMS, content designers may need to become more familiar with how software projects are built and they will need to be comfortable writing and editing content within the software repository.

We think content designers should:

  • be involved from the beginning of a project
  • agree with their team if content should be externalised and, if so, which tokens should be used
  • be familiar with Git concepts like branches, commits, and pull requests
  • know and understand their team’s preferred data storage formats (eg YAML or JSON)

Why are we doing this?

The overall objective is to iterate content more quickly, more easily and more often. This can be achieved by enabling the:

  • content designers to write content, and update the service by themselves
  • user researchers to test this content with users, and feedback results quickly
  • designers to update designs where necessary to reflect new content
  • developers to save time by not having to copy and paste content

This all means more content testing, more often.

There is already some great work going on with content designers across government to learn how to use Github. We’ll let you know how we get on here in Home Office Digital.

Would this approach work for you? Have you got a better idea? We’d like to hear experiences of other projects in the comments.


Leave a Reply