Paraqlet Style Guide

Overview

Paraqlet Solutions is a new Seattle-based communications consulting firm that specializes in supporting African-owned small- and medium-sized businesses in the Pacific Northwest. They provide support for a wide variety of communications-related activities, from event management to social media marketing. Paraqlet needed support in the form of documentation to ensure their communications across different platforms is consistent with brand voice and tone, supported accessibility and inclusion, and maintained cohesiveness.

As a Web Designer for Paraqlet Solutions, I created a style guide site using the static site generator Antora and published it via Cloudflare Pages with automated build and deployment via a CI/CD pipeline. In all, I authored a comprehensive guide on a user-friendly site, all built using a modular, streamlined system for scalability as the company grows in size and operational complexity.

You can view the Paraqlet Solutions style guide on the Cloudflare Pages site.

Process

Paraqlet had a few pieces of their brand guidelines in place prior to my onboarding: their mission, vision, and values; brand voice and tone; and logo and brand guidelines. I translated these guidelines into AsciiDoc for a strong information architecture and modular documentation, which supported readability and scalability. Additionally, I chose to use Antora—a static site generator with out-of-box support for AsciiDoc—so my colleagues could access the style guide on the web. This ensured the guide is a polished, accessible resource that embodies usability and UX best practices.

I began by generating the basic file structure for Antora and formatting the existing documenting with AsciiDoc headings, examples, and ordered and unordered lists. These components ensured the documentation is readable and minimalist in style.

In addition to migrating existing documentation onto AsciiDoc, I also created original documentation for grammar and mechanics, formatting and guidelines for different content, and accessibility and inclusion. I created three different user personas (see below) to help me prioritize content. One persona, Social-Savvy Samantha (see below), was based off of two team members in charge of social media content strategy, so I prioritized this persona.

Three user personas I created early on in the process of authoring the Paraqlet style guide to align my content with the needs of the cross-functional team.

I referenced the Microsoft Manual of Style to build out some basic grammar guidelines, such as for active and passive voice and placement of commas and colons. I chose this guide because it is ideal for user-friendly writing. In adapting an existing company's guidelines, I needed to ensure the Paraqlet style guide was still unique by being conscientious in choosing which guidelines to include, which to not include, and where to let my guidelines diverge.

For instance, I adapted guidelines around grammatical mood from the Microsoft Manual of Style because it's important for Paraqlet's writing to be conversational in tone and cohesive in style. Applying the same grammatical mood throughout the same contexts (e.g. imperative mood for usage instructions) would help with that, and there was no need for me to change widely accepted grammar guidelines.

Similarly, I referenced the Web Content Accessibility Guidelines (WCAG) 2.2 for accessibility guidelines. Using an accepted industry standard guide would help Paraqlet stay on the cutting edge of content and enhance accessibility for web and social media content. I ensured the style guide documented WCAG 2.2 guidelines and embodied them by editing the codebase to align with standards for responsive web design.

After I drafted the guide, I worked on customizing Antora's default UI to suit Paraqlet's needs—namely encoding the accent colors for the site based on the branding guidelines, adding the logo for the site's favicon, and adding the appropriate attributions to the site's footer. I drew upon my HTML and CSS coding skills to efficiently customize the UI.

My next step was to deploy the guide on the web. I used Cloudflare Pages because it supports private GitHub repositories like the one I stored my style guide documentation on, and it offers automated deployment with a CI/CD for seamless content updating.

The dashboard of Cloudflare Pages, which I used to automate site build and deployment via a CI/CD pipeline.

Through the entire process of creating the style guide, I took a user-centered, Agile approach, from starting based off of user personas to leveraging UI design best practices and web accessibility guidelines, to gathering qualitative survey feedback from my teammates and continually translating them into new features for the guide.

For instance, when a team member suggested clarifying grammar and mechanics examples by adding incorrect examples alongside correct ones and differentiating between the two with emojis, I added an extension to the project that allowed emojis to be rendered, then added incorrect examples to pair with existing correct examples. I did so for the Grammar and Mechanics and Voice, Tone and Values sections, ensuring user insights transformed into real improvements.

Challenges

Writing the style guide for a small company with limited branded communications to start with introduced a challenge: How do I ensure the style guide itself embodies the guidelines within?

I aligned the writing of the guide with the guidelines themselves through three primary methods:

• Establish core principles: When I was first designing the guide, I established a couple key guidelines to follow for all my writing, such as writing in active voice, using the imperative mood, using jargon-free language, and providing clear explainations for grammatical terms. These principles enabled my writing process to be smooth and consistent throughout the build process. I also made sure to follow best practices for responsive web design—for example, by ensuring the site content remains functional when the user zooms in by editing the Antora UI's back-end Javascript and CSS code.

• Consistent use of spacing, headings, capitalization, and lists: Writing in AsciiDoc empowered me to easily maintain consistent heading levels by typing equals signs at the beginning of headings.

• Read aloud and gathering feedback: When I completed a section of the documentation, I read it aloud to ensure the text flowed smoothly prior to publication. Likewise, I asked my peers for feedback as I published new pieces of documentation. Prior to publishing the Antora site, I asked for feedback on a set of PDFs I generated from the AsciiDoc files. Later, I garnered feedback on the site itself and used it to improve my style guide.

Another challenge I faced was ensuring my writing was appropriate for non-technical audiences. I worked with the assumption that my colleagues didn't necessarily understand grammar jargon like "suspended hyphen." I asked myself, How do I ensure my Grammar and Mechanics guidelines are comprehensive and clear?

I balanced specificity and completeness of my guidelines with clarity and brevity through two primary methods:

• Define technical terms first: Whenever I needed to use a technical term in my guide, I made sure to define it in plain language and provide a simple example of its usage prior to defining the specific usage guideline. For example, for the guidelines on suspended hyphens, I first define what a suspended hyphen is, then include an example sentence that uses suspended hyphens. Then, I go on to provide guidelines for using suspended hyphens in writing for Paraqlet.

• Use narratively consistent examples: Throughout all the pages of my style guide, I kept examples internally consistent, using the same personas to illustrate different concepts. For example, hypothetical people named in the Proper attributions for media section on the Formatting and Content page are reused in the Captions and transcripts section on the Accessibility and Inclusion page. This creates a sense of narrative flow, enhancing understanding while improving user engagement.

Conclusion

By creating structured, modular AsciiDoc documentation and automating deployment with Cloudflare Pages' CI/CD pipeline, I created a style guide that supports all aspects of Paraqlet Solutions' early content creation and is set to seamlessly scale alongside the company.

The finished style guide didn't just codify guidelines to maintain consistency and cohesiveness in communications for Paraqlet Solutions. It became a living, consistently improving documentation that supported a small but mighty team with strong promise for growth.