Technical Content Style Guide

The WorkOS style guide for technical content. Our descriptive guide to writing blogs, tutorials, and technical documentation for developers by a developer.

Coding is easy, writing is hard. We like to joke here that as developers, we're great at writing words… just not in full sentences! However, producing great technical content is a core part of the WorkOS DNA, and so we've had to learn how to do just that (thank you Justin Gage for the early guidance).

Below, we've shared our style guide for technical blogs, tutorials, and documentation. It is meant to be descriptive, not prescriptive, and was written by a developer for other developers… writing for developers.

Guiding principles

The audience for WorkOS content (i.e. blogs and documentation) is software engineers. The content we publish should:

1. Demonstrate deep expertise to develop trust with readers. “They are a developer and they’ve dealt with my problem” is the perception we should cultivate from developers.
2. Be respectful of readers’ time by always being valuable. Our content should not be thinly veiled sales pitches or lazy fluff for the sake of volume.

In short, be that one really amazing instructor who was not only deeply knowledgeable, but also knew how to communicate effectively, and was still cool, relatable, and enthusiastic about teaching.

Voice and tone

Content should strive to be relatable, like we’re on the same team as the readers - think the Principal Engineer who never makes you feel stupid and is delighted to share knowledge and participate in your growth. Let’s go on an adventure of learning together!

1. Human. Be educative but deeply empathetic, an expert but quietly confident.
2. Wry. Give the readers a wink sometimes with humor they can relate to. Big companies are generally less able to make knowing references to internet culture / the overall zeitgeist. Us doing this makes it clear that WorkOS gets it.

Language

Content should read as though written by a developer for developers.

1. Clear. Avoid jargon and slang. Acronyms and abbreviations should be explained on first reference.
2. Simple. Get to the point and avoid unnecessary complexity, redundancy, and verbal garnish.
3. Accurate. Be specific and use terminology and phrases used by developers.
4. Inclusive. Not only do we want to engage the readers, we want to include all of them. When writing about fictional people, switch up the pronouns (he / she / they) and consider using names from different cultures. Be judicious about cultural references that could be lost on some readers.

Grammar and mechanics

Correctness matters but don’t get too hung up on perfection and minutiae. While Mailchimp’s guide is good enough for most specifics, below are some additional rules to follow.

1. Favor (un)ordered lists over inline lists to break up walls of text and make content easier to scan and digest.
2. Capitalize the start of every list item and end with a period.
3. Use italics and bolding to emphasize and highlight important takeaways.
4. Headings should use sentence case instead of title case.
5. There should be a single space before and after dashes and slashes, i.e. “foo / bar ” and “foo - bar”.
6. There should be a single space after periods.
7. Use Oxford commas, i.e. “foo, bar, and baz”, not “foo, bar and baz”.
8. Use block quotes when quoting more than a sentence. Anything shorter should be quoted inline.
9. Keep sentence structure simple, e.x. avoid more than three nested or chained clauses.
10. Use abbreviations or domain slang when possible to keep the voice human, e.x. “specs” instead of “specifications”, “JS” instead of “JavaScript”, and “local dev” instead of “local development environment”.

Content and structure

1. Be factual. Avoid phrases like “some have said that” and instead use positive assertions that you could provide evidence for if asked. Engineers are on alert for claims they can poke holes in, and once found, their trust in us is shattered. Be careful not to use social proof as a crutch. If referring to a user, describe exactly the value that the user receives from the product or feature.
2. Link to docs or more details whenever appropriate and possible 🔥‍
3. Use examples. Abstract ideas or descriptions of complex processes should be clarified and augmented with examples, i.e. code snippets, diagrams, analogies, graphs, screenshots, GIFs, and etc. Code snippets should be in Python >= 3.7.x if the content is not language-specific. All code snippets should be functionally correct, use code formatting, and follow generally accepted style rules.‍
4. Don’t be afraid to get technical. Since we expect our audience to feel comfortable reading a fairly technical document, including technical details can not only be clarifying, but also make it clear that our content is not just an arm of our marketing function.‍
5. Provide context. Give the reader a starting point so they understand the purpose, scope, and value of the content we’d like them to consume. What is the problem we’re solving, the use case we’re examining, or the idea we’re presenting?

Concluding notes

1. We respect our readers but should maintain a beginner's mindset. Our content should strive to strike a middle ground between being deeply technical but also deeply empathetic to more novice readers.
2. While blogs, tutorials, and docs are not explicit marketing material, they still shape brand perception and will drive inbound traffic. Polish, usefulness, accuracy, and integrity matter, but so does engagement.

Technical blogs we like

1. Segment
2. Stripe
3. Riot Games
4. CircleCI
5. WorkOS 😉