Saving time and reducing rework with DRY code

Programmers have an adage to help them simplify code and reduce duplication: don't repeat yourself (DRY). This advice exists to help them remember to single-source frequently used bits of code into separate files that can be included in multiple places. Following the DRY principle cuts the time it takes to make updates in multiple places and reduces errors. 

As it turns out, this advice is also useful for Fastly's documentation team, which I’m a member of. We use certain sentences and phrases dozens of times throughout our documentation, and we've found it useful to put some of those phrases into one place that can be referenced in multiple guides. This helps us standardize our documentation, reduce copy and paste errors, and eliminate some of the headaches associated with documentation updates due to interface changes, which means we respond to changes more quickly and deliver updates to you faster. It also helps us support translated versions of documentation. Single-sourced content has allowed us to quickly translate from English to Japanese, with the ability to easily add more languages.

Because we find this so helpful in our workflow, I thought I’d show you how we did it in case it can help you in yours. Let’s get into it. 

In order to adhere to the DRY principle, we leveraged a built-in functionality in our static site generator, Jekyll. Jekyll has a method for single-sourcing content called data files which allowed us to create files containing key:value pairings which we refer to as DRY keys. 

Creating DRY keys was easy. We simply created a _data folder in our repo and a YML file to store the DRY keys — one for English DRY keys (en.yml) and one for Japanese DRY keys (ja.yml). Within each YML file, we organized the DRY keys in key:value pairs. Example:

my-dry-key: “Insert text for DRY key.”

Note: Both YML files contain the same key name, but the value is translated into the target language. 

The harder part was determining which text to turn into DRY keys. We decided to create DRY keys for the the headings of the alert boxes you see throughout the doc site, because these are referenced quite often:

alert-leader-tip: "TIP" 
alert-leader-note: "NOTE"
alert-leader-important: CAUTION
alert-leader-warning: "WARNING" 

We also created DRY keys for the most common steps referenced throughout the documentation site. These probably look familiar to you: 

step-login: "Log in to the Fastly web interface."
step-login-configure: "Log in to the Fastly web interface and click the **Configure** link."
step-login-account: "Log in to the Fastly web interface and click the **Account** link from the [user menu](/en/guides/about-the-web-interface-controls#about-the-user-menu. Your account information appears."
step-select-service: "From the **All services** page, select the appropriate service. You can use the search box to search by ID, name, or domain."
step-click-edit: "Click the **Edit configuration** button and then select the option to clone the active version. The Domains page appears."
step-click-origins-tab: "Click the **Origins** link. The Origins page appears."
step-click-settings-tab: "Click the **Settings** link. The Settings page appears."
step-click-content-tab: "Click the **Content** link. The Content page appears."
step-activate-deploy: "Click the **Activate** button to deploy your configuration changes."

How does this look in practice? To use a DRY key in documentation we simply reference it in a Liquid tag as follows:  {% t my-dry-key %}.

Our custom Jekyll plugin reads each DRY tag and outputs the value of the DRY key. For example, consider this section from the Uploading custom VCL guide: 

Here’s how that guide looks behind-the-scenes:

1.  {% t step-login %}
2.  {% t step-select-service %}
3.  {% t step-click-edit %}
4.  Click the **Custom VCL** tab. The Custom VCL page appears.
5.  Click the **Upload a new VCL file** button. The Upload a new VCL file page appears.

The t indicates that the code (through some behind-the scenes magic) should use the language of the page to get the appropriate translated version of the DRY text. Translation is costly, because most translation services charge per word. Japanese DRY keys help us save on translation costs because we can pay to have a phrase translated once, but it’s used in multiple places.

For our initial roll out of DRY keys, we had to do several instances of find-and-replace to insert the DRY keys into the appropriate spot in the documentation. But now, if something in the Fastly interface changes, we save ourselves time by only having to update a central location in order for the change to appear across the site. This helps us deliver updates faster to you and reduce the chance of making mistakes or missing a guide that needed updating. 

Additionally, this system allows us to scale when we decide to add new translations for our documentation. All we’d have to do is take the existing DRY key file, copy and rename it, and then have those key values translated. 

There’s a bit more work involved that would require an explanation of our home-grown translation system, but we’ll save that story for a future blog post!