Branding and style guides defense in depth: Establishing the physical boundaries
By: Cory Fowler
Tags: Automation, Documentation, Continuous Integration, Docopt

Undoubtably, looking at the title of this article you are likely intrigued as to where this post is headed, given we’re already mixing disciplines, but before we get into that, allow me to take a moment to talk briefly about myself.

I’m a self taught script kid, turned formally educated software developer, advocate, program manager, documentarian and *coming soon* privacy technologist. I guess what I’m saying is, I have a metaphorical hat collection, I change them up and occasionally I try them all on at once.

To start, I’m borrowing from my software developer background and leaning on the concept of Defense in Depth which outlines three categories for protecting a system against attack: Physical controls, Technical controls and Administrative controls.

Similarly, protecting company branding, uniformity, and consistency of the documentation, there are layers in the process of creating content that can be influential to the final result. Let’s explore some of the different dimensions to consider when attempting to protect your brand in your documentation site.

This is part 1 of a 3 part series:

* Establishing the physical boundaries

* Employing your toolbelt

* Building light touch processes

Fundamentals

To better understand the layers of the in the process, this post covers the scenario of a statically generated website, with a distributed group of content editors working through a public version control system.

Components of the website:

Static Site Generator

Public Source Control System

Formatting with Markup Language markdown

Various other tools (more details later)

Establish the physical boundaries

Starting into the defense in depth strategy, lets consider the physical locations where interventions can be made to content for branding, style & voice guidance, as well as accessibility considerations throughout the creation of the content.

Physical boundaries of the system are places in which the content can be modified to change it’s appearance to the end user.

In order to break this down, lets categorized the physical locations to two zones: Client side, and Server side.

Client side zone

The client side zone are the areas of impact on style and branding considerations on a computer or laptop of either a viewer or contributor of your content.

Browser

Many things in the user experience can be manipulated in the browser by using technologies such as Cascading Style Sheets (CSS) and JavaScript. These technologies can adhere to formatting rules, such as capitalization or sorting guidance.

Considerations for user experience:

Does it apply to a broad spectrum of your content?

Is it mostly a formatting or esthetic guideline?

Is it safe to ignore the source formatting for this particular element?

Additionally, it is possible assist your contributors with a browser extension. A browser extension can be programmed to assist with contributions in a variety of ways. It can help extend the functionality of the browser to assist in collecting relevant information for creating content, or extend the functionality of a website to streamline an experience to assist a contributor.

Considerations for a browser extension:

Does the contributor spend a lot of time transposing text from a website?

Does the majority of your contributors use the same browser or is the extension cross compatible within your contributors browsers of choice

Text Editor

A text editor can provide a means of speeding up contributors by providing templates, formatting assistance and preview capabilities out of the box. In addition, it is possible to extend curtain text editors to expand the built-in functionality. This could be an attractive option if you are able to dictate the use of particular tools, or know that your contributor base are comfortable handling a specific toolset.

Considerations for a Text Editor extension:

Can you get the majority of your contributor base to use the same text editor?

Is it possible to provide a consistent experience across a variety of platforms?

Source Control System

This is an unlikely place to put things to help your brand or style guide, however, it is an effective place to help enforce rules for your processes locally.

In the Git Source Control System, there is the concept of hooks which allows your to run custom scripts when important actions occur. If the script errors out, the operation is aborted and doesn’t allow the contributor to advance in the contribution process.

This could help enforce specific requirements that are needed from a source control perspective such as formatting a commit message with specific format or enforcing a file naming convention.

Considerations for Source Control Hooks:

Does the system rely on specific information to be provided as part of a commit message?

Are there specific requirements in a filename or folder path that needs to be avoided?

Can you provide a contributor enough information to help resolve the issue with limited assistance?

Server side zone

The server side zone are the areas of impact which are processed on 3rd party service, such as a public source control system, or cloud platform.

Continuous Integration

Having a continuous integration pipeline provides the ability to execute scripts, or utilities on every check-in to the repository. Ensuring that the top priority branding elements are present before accepting a contribution to be build, can save overprocessing. This could be implemented using a feature of your source code provider (like GitHub Actions) or provided by a third party company (like Travis CI).

Included in the continuous integration system should provide a build system to be able to check the output. Defects can be discovered by post-processing the compiled pages, this can be achieved by using tools such as Browser Stack.

Considerations for Continuous Integration:

Is this something that needs to be reviewed with every check-in?

Are there branding or style guidance that should not be able to make it into the source, such as offensive language.

Compiler Extension

With the system leveraging a formatting language, such as Markdown, it is possible to extend interpreter to introduce new formats. Leveraging an extension could provide the means to simplify the creation of complex html output.

Considerations for Compiler Extension:

Is there a complex element (or element properties) that is needed for the content? (think accessibility)

Could the same functionality be implemented in other areas of the system?

Automation

It’s also possible to configure a continuously running job to periodically scan the documentation at rest to ensure that the branding and style guidance has been followed. This could include a link checker, self-healing documentation tooling or any other processes that would help assess the body of content which isn’t constantly updated.

Considerations for Automation: