Draft.dev Visual Style Guide: Formatting Standards

April 11, 2024

Chris Wolfgang

4 min read

processes

TL;DR: Draft.dev’s visual style guide demonstrates consistent formatting standards:

Markdown in Google Docs ensures universal compatibility across all content management systems without unexpected formatting
Title case headers provide visual hierarchy and structure, following Chicago Manual of Style guidelines
Simple code snippet formatting with inline code for short segments and standalone blocks for larger code samples
Editorial hierarchy prioritizing house style, then Chicago Manual of Style, then Merriam-Webster for consistency

This approach guarantees consistent, professional technical content while accommodating client-specific style preferences when needed.

If you’re curious what a completed Draft.dev article might look like, here you have it. This article serves as a visual demonstration of our house style (eg, our default formatting for text, code snippets, and images, as well as a peek into our copy editing standards).

What’s actually written in the text of this visual guide doesn’t particularly matter, but Lorem Ipsum is boring. So if anyone’s interested in why Draft.dev’s style guide is the way it is, they’ll find some insight here.

You can find the in-depth style guide used by our editorial team here, if you’re curious and want to see just how deep our attention to detail goes.

Why Draft.dev Uses Markdown for Technical Content

For starters, all of our articles are Google Docs written in Markdown. This ensures a couple of key functions:

Our clients don’t have to learn new tooling. The Google suite is familiar throughout the business world, from developers to marketers. So no matter who is handling a client’s content, they’ll most likely be able to easily work with a Google Doc.
Markdown formatting is universal. No matter the client’s content management system, their text editor will know exactly what to do with Markdown. Providing our articles in Markdown ensures that no unexpected formatting ends up in the client’s published content—no matter where they publish it. Any branded fonts and colors and spacing will lay out exactly as the client expects them to.

Want to see what the Markdown looks like before you put it in your CMS? Check out a Markdown editor like Dillinger for a preview.

Editorial Standards Hierarchy and Style Sources

To ensure consistency for all our clients, we’ve built a robust style guide for our editorial team to follow. Our style includes standards from a few common style sources, generally in this order:

House style. These are standards that our editorial team has decided on in-house. If our editorial team is unsure how to resolve an edit, they check this guide first.
Chicago Manual of Style. A common standard for long-form writing, the CMoS sets down rules for everything from formatting to comma use.
Merriam-Webster. The online collegiate edition is our go-to for spelling.

Note that Draft.dev uses American-English spelling and punctuation.

Title Case Headers for Consistent Visual Hierarchy

If a client’s content marketing has decided on any style standards, chances are they’ve made a decision as to how they want headers to look. Headers are typically a short phrase in a larger/more distinctive font to add structure and context to paragraphs within long-form content.

Draft.dev uses title case for headers of all hierarchy; that means most words (but not all; CMoS is very stern about this, sorry about that) in a header are capitalized.

If our clients prefer sentence-case headers (ie, only the first word is capitalized), we can accommodate that too!

Simple, Effective Code Snippet Formatting

While short lines of code can be kept in-line (eg, <ButtonText>) with the rest of a paragraph, larger blocks of code stand on their own, like this:

<Buttons>
    <Button guid="guidOktaAuthVsixPackageCmdSet" id="MainToolWindowCommandId" priority="0x0100" type="Button">
        <Parent guid="guidSHLMainMenu" id="IDG_VS_WNDO_OTRWNDWS1"/>
        <Icon guid="guidImages" id="bmpPic1" />
        <Strings>
          <ButtonText>Okta Extension</ButtonText>
        </Strings>
    </Button>
</Buttons>

To ensure language-specific syntax highlighting for the code block, a client’s content management system will most likely require a plugin.

Consistent Standards With Custom Flexibility

Draft.dev’s house style promises consistency and standard elegance through a highly detailed set of standards established by a team of experienced editors. However, if a client requires the use of their own style standards we can tailor our services to your style guide too!

Frequently Asked Questions

Why does Draft.dev use Markdown instead of other formatting options?

Markdown ensures universal compatibility across all content management systems without unexpected formatting issues. Clients don't need to learn new tooling since Google Docs is familiar throughout the business world. Markdown formatting works consistently in any text editor, ensuring branded fonts, colors, and spacing appear exactly as clients expect when published, regardless of their CMS platform.

What style guides does Draft.dev follow for editorial standards?

Draft.dev follows a three-tier hierarchy: house style standards developed by the editorial team for consistency, Chicago Manual of Style for long-form writing rules covering formatting and punctuation, and Merriam-Webster online collegiate edition for spelling standards. This hierarchy provides clear decision frameworks when style questions arise during editing, ensuring consistent quality across all content.

Why does Draft.dev use title case for headers?

Title case headers provide consistent visual hierarchy and structure in long-form technical content. Most words in headers are capitalized following Chicago Manual of Style guidelines, creating professional appearance and clear content organization. Draft.dev can accommodate sentence-case headers where only the first word is capitalized if clients prefer that style for their content marketing.

How should code snippets be formatted in technical content?

Short code lines can be kept inline with paragraphs using backticks, while larger code blocks stand alone as separate formatted sections. This simple approach maintains readability without overwhelming text flow. Clients' content management systems typically require plugins for language-specific syntax highlighting in code blocks, but the basic Markdown formatting ensures consistent presentation across platforms.

Can Draft.dev adapt to client-specific style guides?

Yes, Draft.dev's house style ensures consistency and standard elegance, but the team can tailor services to accommodate client-specific style standards when required. This flexibility allows Draft.dev to maintain its quality standards while respecting clients' established brand guidelines and formatting preferences for their content marketing initiatives.

What are the benefits of using Google Docs for technical content?

Google Docs provides familiar tooling throughout the business world for both developers and marketers, eliminating learning curves for clients handling content. The Google suite's universal familiarity means anyone managing client content can easily work with Google Docs, streamlining collaboration and review processes across technical and non-technical stakeholders.