Should content be hardcoded or externalised?

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.

How does externalising the content affect me?

This will affect all members of agile 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.

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

3 comments

I agree that content should be externalised. As you say, it's more flexible and more efficient when it comes to supporting multiple languages. It also potentially reduces the risk of code errors too, since there are less code changes occurring.

Additionally, it can reduce maintenance as content that is used across multiple pages (e.g. a telephone number) can be defined once in the external content file, but called by the code on multiple pages. So, if the number changes, only the single reference to it in the content file needs to be updated.

When you say "bringing the content out of the code into a separate content file", I assume you mean that this content file is still within the package of files that forms the code build. Whilst this would give Designers the flexibility to update content themselves, it still means that they'd have to be part of the build process with all that entails - e.g. having to get familiar with GitHub to produce builds or having to wait on others to do builds (which, if the build is broken, could cause a delay).

A different option might be to have a content file that lives outside of the build and is hosted somewhere that the code can reference. That way, content changes can be made independently of builds. It also means that content could be managed / published via systems that are a bit simpler (e.g. a basic CMS) than having to use GitHub (which I've found to be a bit painful when there is complex branching and multiple contributors). One downside though is that testers would have something external to the build which can affect their testing (e.g. code build v1 and content file v1, could produce different results to code build v1 and content file v2).

Finally, if an external content file is going to be used, it would help if the format of it allows the content 'elements' to contain basic HTML. Otherwise, if the Designer wants to split a line of text into 2 paragraphs, for example, they'd still be reliant on a developer to amend the code to call 2 content elements, rather than 1. Failing that, perhaps it'd be better to make the content external only when the page flows/layout are fairly stable.

If a standard approach can be agreed, it might be possible to build up a standardised nomenclature for the elements in the content file, e.g.:

"page-name.page-title"
"page-name.intro-text"
"page-name.button-text"

This framework could then be used as a starting point for each project, which should reduce the time in creating the content file and in pointing the code to it.

Fantastic article. It's the way I've always worked on big blue-chip projects and what I've been advocating for the past 18 months at DWP. I shout 'give me strings' on a weekly basis. The main hurdle is an unfounded fear that this will destabilise a fragile code-base.