How documenting helps everyone understand design

By Tom Bird

Communicating effectively in a large organisation with cross-functional teams can be a challenge at the best of times — add to that a time-intensive project, remote working and a varied understanding of design terminology, and the challenge ramps up.

That’s exactly what the Wireless design team was faced with when Virgin Radio UK tasked us with completely overhauling their existing website to house a plethora of new content.

This is how documenting our processes and naming conventions helped us meet the challenge.

What’s in a name?

In order to present content to the user in an engaging way, we designed a suite of reusable, multi-purpose layouts which would encourage an increase in consumption across the various sections of the site.

In doing this, we quickly realised that different disciplines naturally refer to elements of design in different ways — and that without efficient documentation on a large project, things can quickly get lost in translation, especially whilst working remotely and asynchronous feedback is the norm.

Enter our design system team

In order to avoid confusion and ensure each team fully understood how the content layouts behaved, we collaborated with NewsKit, our design system team, to create detailed documentation of the site — this would become a single source of truth moving forward.

Why the design system team?

• They’re used to documenting in granular detail and do it for everything they create.
• They’re across all teams and know exactly how people work and understand projects.
• They’re extremely experienced in communicating complex ideas to audiences with varying levels of technical abilities.
• They went down the exact same rabbit hole when designing their own website and documented the entire process with great success.

Here’s the process we followed in documenting our single source of truth for Virgin Radio UK site.

Step 1: Outline site hierarchy

Our first step in establishing a uniform naming convention was to identify the site structure and hierarchy. The goal was to understand how the different pages related to one another — this ground work would then help to determine the purpose of each content layout.

Tier 1: Home page

The home page is a unique page with no re-use across the Virgin Radio site. It provides a platform to listen live as well as providing a high-level taster of content categories.

Tier 2: Index pages

Index pages act as a gateway into each of the defined content categories on the site. They provide an overview of the most recent and popular articles in a given category.

Tier 3: Article pages

Article pages are used to house a singular story or publication and make up a large proportion of pages available on the site.

Step 2: Map the site

With the hierarchy established, we were able to workshop with stakeholders to identify a V1 expected site map, which included tags to communicate which page template each section would utilise.

Step 3: Define sections

With everyone in agreement on navigational structure, the next step that needed documenting was the page structure.

Sections of the site’s pages are broken down into sub-categories to allow for easy differentiation between any that have similar names or use cases. The current existing categories are:

• Navigation: Any core navigational component that allows users to move between pages or between sections of the same page. Key examples are navigation-header and navigation-footer.
• Header: A section that sits at the top of a page. These are primarily used to introduce and give context to the page, as well as to house the player component on the home page.
• Content: Section components that sit within the page’s primary content area. These form the basis of the page content itself. Examples of this are the content-generic and content-sidebar.

Step 4: Establish naming conventions that work for everyone

Using the previous steps we’d followed, we were able to establish naming conventions for our content layouts that made sense to both business stakeholders as well as engineers.

The key here was to avoid being too specific and focusing on the use case — instead it was based around the location and make-up of each layout.

The agreed format followed this structure:

{section category} — {descriptor} — {variant}

Combining this naming convention with a breakdown of props for the engineers, and detailing the breakpoint behaviour of each layout, guaranteed that our designs would be translated as expected when moving into development.

The result

The end result of this exercise was a concise Confluence document that each team could refer to — which was just the right amount of detail needed, depending on who was looking at it. An example of the final documentation is shown below.

{content} — {feature} — {base}

Visual layout and props

Description

The {feature} section chronologically displays the latest articles from a particular category.

It consists of 1 large vertical feature card, and 4 smaller horizontal cards. The section includes a title and a link pushing to an index page.

Breakpoint behaviour

Key learnings

The key takeaway we took from this redesign was that not everyone processes and understands design in the same way. By documenting the small details, there is a lot less confusion amongst teams and we have effectively set up the foundations of future projects.

The Virgin Radio UK website is making great progress — look out for the official launch in the coming months.