Shortcode Markup: An Implementation Guide

As budgets tighten and AI looms, marketing teams are under pressure to keep operating costs to a minimum while outputting work faster than ever. There are thousands of ways to build more agile, efficient departments, but, in this article, we’ll focus on removing friction – specifically, the friction between copy and design teams.

Rendering copy into a usable design can be hard, especially if the copy doc is raw (that is, a Microsoft Word or Google Doc page just filled with unformatted text). Design teams are forced to spend time thinking about what goes where and how the copywriter intended their content to look and flow.

At first, this point of friction seems insignificant. Cumulatively, though, it starts to have an effect. When friction occurs across hundreds of tasks, it costs significant time and money and can also compromise quality.

My solution: design enablement via shortcode markup. I’ve been testing these two concepts in field environments for the past year or so, and, almost always, they translate into better design results and better approver feedback without any extra project costs.

Shortcode markup has become the default Chevron Editing style for technical copy and content tasks. With this guide, you can make it part of your team’s workflows too.

What Is Design Enablement?

Design enablement is a copywriting and content creation methodology that helps graphic and UX designers do their best work. Too often, copy is handed directly to designers as a Microsoft Word document in a format that looks something like this:

Under design enablement principles, this deliverable is unacceptably ambiguous – the recipient designer must essentially guess the intentions of the copywriter. Instead, copywriters and content creators need to effectively communicate their intentions, allowing designers to focus on creating exceptional web pages, apps, brochures, and infographics.

What Is Shortcode Markup?

Shortcode markup is a copywriting style that draws inspiration from WordPress’s shortcode system, which involves dynamically replacing bracketed macros with content using PHP. Shortcode markup embraces a similar principle – bracketed content serves as a stand-in for design ideas, allowing copywriters to quickly and easily draft functional layouts.

Here’s an example:

In the above instance, there are two shortcode markup elements: ‘[hero header]’ and ‘[CTA]’. ‘[hero header]’ is a trammelled element – it has an opening and closing shortcode, which indicates that the content between them is included within the shortcode (more on how this works shortly).

Why Do Marketing Teams Need Shortcode Markup?

In most go-live flows I see, there is a gap between the copywriter’s intentions and the understanding of those intentions parsed by the designers.

Ideally, copywriters and designers should collaborate on pieces, working together in synergy to produce a refined, conceptually sound deliverable that everyone loves. In reality, though, timelines and team structures mean this rarely happens.

Instead, the scenario normally goes one of two ways:

1. The copywriter submits a raw MS Word/Google Docs file with minimal formatting. Cue guessing games from the design team.
2. The copywriter practices their design skills, spending time rendering the copy via wireframes/mockups.

The first option has multiple problems. One, both approvers and designers have trouble visualising what the end deliverable should look like. This means reviews are less effective and designs struggle to incorporate the copy in the right way.

Two, designers spend time and cognition attempting to understand the copywriter’s intentions. This leads to higher project costs and a heavier cognitive load for your design team.

Three, the copywriter may not have actually visualised the copy in its final form, which can result in copy that is not fit for purpose – too much text on brochure pages, for example, or a web page that’s missing critical elements.

The second option (letting the copywriter mock up their work) also has issues. The first problem is that you’re essentially paying the copywriter twice over – once for the words and once for putting those words into a rudimentary design (which possibly won’t be to a professional standard). This leads to significant increases in timelines and project costs.

Secondly, if your copywriter does submit their deliverables in a PDF/image/formatted Word doc, approvers subsequently struggle to make changes and separate the copy from the design. Poor design from a copywriter can make their words seem less suitable than they actually are, implementing edits takes the copywriter more time, and no editor likes trying to mark up changes in Adobe Acrobat.

Shortcode markup offers a bridge between these two scenarios. With a set system of shortcode elements in place, everyone involved in the project can instantly understand the intended layout of the copy. For copywriters, shortcode elements can be easily added to MS Word or Google Docs – there’s no additional software or time required.

The result: designers don’t have to guess at layouts, copywriting costs less and ships faster, and approvers can make recommendations with full context.

How Shortcode Markup Works

Shortcode markup pairs built-in word processor styles with shortcode elements – bracketed terms that act as signifiers for design concepts.

Headings are indicated using the H (H1, H2, H3, et cetera) styles in MS Word or Google Docs. Body text is formatted normally, with a font size of 11 or 12 points, a sans serif font like Calibri, and an easy-to-read line spacing (I recommend multiple line spacing at 1.08 points with a 12-point break after each carriage return).

This consistency makes it easy for everyone involved to understand exactly which text is a heading instead of, for example, bolded body text. If you’re copying content directly into a CMS like WordPress, headings will also copy over into rich text editors, which reduces the workload for your web developers.

Design concepts (for example, brochure pages, hero headers on websites, images, or HTML accordions) are all indicated using shortcode elements. These will be replaced during the design or upload stage (depending on your process) with the concepts that they represent.

Shortcode elements are either self-contained or trammelled. Self-contained elements are wholly replaced with the respective design concept – for example, ‘[image]’ would simply be replaced with an image of the designer’s choice.

Trammelled elements are slightly more complex. They feature an opening shortcode and a closing shortcode, the latter of which is indicated by a forward slash behind its first bracket; any content in between the two shortcodes will be included within the element.

It’s important to understand that shortcode markup exists to clarify copywriter intent, not inform design per se. As such, the diversity of shortcodes is deliberately limited. For example, using ‘[image]’ instead of ‘[photo]’ leaves the choice up of whether the image should be a photo, a graphic, or an illustration up to the designer.

If additional instructions or details are required beyond what shortcode markup enables, add them using in-document review comments.

Implementing Shortcode Markup Within Teams

Shortcode markup is purpose-built for easy implementation. Your copywriters should have little, if any, trouble understanding how it works, and your designers and web developers are likely already familiar with the concept of WordPress shortcodes.

Firstly, put aside half an hour for your team members to read this blog. Once they understand and identify with the issues we’ve discussed here, they’ll be more willing to try something new.

Secondly, add this URL (https://chevronediting.com.au/shortcode-markup/) to your team’s Slack, SharePoint, or Coda instance, preferably in the same place as your brand voice and textual style guides. Make sure you add a section on shortcode markup to your style guide too.

Thirdly, collect feedback at regular intervals. Expect initial pushback (new copywriting styles are rarely greeted with joy) followed by total adoption. If shortcode markup doesn’t work for your people, though, don’t force it – I’ve tested it across many client scenarios, but it may not be the right fit for you, and that’s fine.

Fourthly, whether implementation succeeds or fails, I’d love to hear how it went. I’ve been testing shortcode markup for about a year, but I expect it will keep evolving over time, and the more data that informs that evolution, the better the end result will be.

Shortcode Markup Guide

Pages and Sections

Page Content

Interactive Objects

Forms

More elements coming soon.