Arctype Style Guide

"Storytelling is the most powerful way to put ideas into the world today." --Robert McKee

If you're reading this post then congratulations! Writing is a rewarding task, but it can be difficult to get started.

We created this guide to share what we think makes a great article, and what we look for during the editing process.

If you're looking for information on what and who we write about/for, please refer to our Writing For Arctype post.

We follow a 3-step process for writing:

1. Outlining
2. Writing
3. Editing

The purpose of this guide is to provide clarity on what we look for in steps 1 and 2 so that we can minimize time spent on step 3.

Outlining

Creating an outline is one of the most important steps in our writing process. We ask every writer to send us an outline before starting a draft in order to prevent editing headaches down the road.

What to include in an outline:

1. What is the focal point of the story?
2. What is the storyline (H2/H3s)?
3. (optional) supporting evidence?

Here are some ways to organize a story if you're struggling to get started:

• Chronology (useful for historical discussions – e.g., how the Mexican War developed)
• Cause and Effect (e.g., what consequences a scientific discovery will have)
• Process (e.g., how a politician got elected)
• Deductive Logic: generalizing 1-2 examples to a broader statement
• Inductive Logic: applying a general statement to a specific example
• Main idea -> 3 pillars -> supporting evidence

Our 3 Golden Rules

1. Get rid of clutter (On Writing Well - William Zinsser)

Prune ruthlessly. Re-examine each sentence you put on paper. Is every word doing new work? Can any thought be expressed with more economy?

2. Clarity of writing follows clarity of thought (The Economist Style Guide)

Think about what you want to say, and then say it as simply as possible

3. Show, don’t tell (Everybody Writes - Ann Handley)

If you are going to tell me what you think, give me a solid reason why you think it. Don’t tell your reader that you feel something; tell them why you feel it. Don’t say what works; tell them why it works and what led you to this moment.

i.e) Instead of saying solution - tell me what the solution is, how it works, and why it’s better. Instead of saying a lot - tell me how many.

How We Evaluate the Quality of a Story

We have adopted the Medium curation guidelines for every story that we publish. The guidelines have been copied here for your convenience:

• Does the story meet a high editorial standard? – Is it well-written, easy to follow, free of errors, appropriately sourced, narratively strong, and compelling?
• Does it add value for the reader? – Does it share new insights or perspectives? Offer an original take on a familiar issue? Does it stir emotions and/or thinking? Provide meaningful advice? Enrich a reader’s understanding of the topic? Does it feel like time well spent?
• Is it written for the reader? – Is the story written with the reader in mind? Does the story make a connection with the reader or to a larger issue?
• Is it complete? – Is it a finished, polished piece of work? Considered? Concise? Will a reader walk away satisfied?
• Is it rigorous? – Are claims supported? Sources cited alongside stated facts? Does the story hold up to scrutiny?
• Is it honest? – Is the story written in good faith? Is it truthful?
• Does it offer a good reading experience? – Is it properly formatted for the web/mobile? Does it have a clear and relevant headline that lets the reader know what the story is about? An easily readable story body — paragraphs/spacing/styling/section breaks/quotes?
• Is it free of typos and errors?
• Is the imagery appropriate? Is the imagery relevant and appropriate to the story?

13 Rules on Writing for the Web

1. Use active voice instead of passive. Active sounds alive. Passive can sound stilted or awkward. i.e. “Sam edited the video” instead of “the video was edited by Sam”
2. Invest time in crafting a good headline
3. Catch the attention of the reader and then get straight to the point
4. Give special love to the first (lede) and last sentences (kicker) of the piece.
5. Try to avoid adverbs.
   • Stephen King is a huge proponent champion for this rule. If you choose the right verbs, there is no need to modify them with an adverb. The dialogue or context preceding the sentence should convey its meaning.
   • Be wary of “intensifier” adverbs: ‘very’, ‘really’, ‘extremely’, ‘incredibly’. Is the adverb completely necessary for the sentence to make sense?
6. Use shorter paragraphs with no more than 3 sentences or 6 lines (example blog)
7. Use shorter sentences with no more than 25 words in a sentence
8. Use straightforward words - avoid clichés, jargon, and buzzwords (i.e. use instead of utilize)
9. Use bulleted or numbered lists
10. Highlight key points with bold, italics, or a pull quote
11. Use H2s and H3s to break up text
12. Add visual elements such as code blocks, graphics, photos, etc
13. Break any of these rules if they violate one of the golden rules

Our Voice

The three pillars of Arctype are collaboration, simplicity, and power. These qualities should influence our voice when we write as well.

Friendly

Collaboration. The core of Arctype is helping people work together. We want to sound like someone our users want to work with. We incorporate this by:

• Writing like you’re talking to a friend
• Using second person (“you”, “we”, etc)
• Sprinkle in questions (but not too many)
• Including light jokes and humor
• Not being overly dogmatic

Helpful

Simplicity. We built a product to help users move as fast as possible. Our writing should answer our users’ questions quickly (and completely) so they can get on with their lives. We incorporate this by:

• Using plain English
• Writing from the perspective of user benefits instead of company buzzwords
• Striving for brevity
• Adding a touch of compassion

Innovative

Power. We are striving to build the go-to solution for database management. We want to be a thought leader in the database industry. Our writing should spark inspiration. We do this by:

• Being experts on the technical details
• Sharing a vision of a better state
• Questioning the status quo
• Writing with confidence

Formatting Conventions

Styles

• While creating a first draft do not worry about the styling. After the post is transferred to our CMS, Ghost, the style will be auto-formatted to match our blog.

Headline (H1)

• Should contain the primary keyword
• Put the keyword first / early in the headline
• Should be specific
• Use active language
• Make the benefit obvious
• Tip: Use numbers or questions
• Tip: Longer headlines (12-16 words) work well
• Tip: Use trigrams (3-word phrases i.e. the truth about, what we know, etc)

Intro

• Don't bury the lede––get to the point quickly.
• Work your primary keyword naturally into the first paragraph
• Example techniques: open with a question, raise the stakes, lead with a personal narrative
• Avoid absolute statements at all costs...consider that readers of all experience levels will be reading this.

H2

• H2s are great opportunities to optimize and rank for related keywords
• Should go a level deeper into your H1, i.e. if your H1 is "Marketing Reporting: Everything You Need to Know," one of your H2s might be "Google Analytics Reporting."
• Don't waste these opportunities with "cute" or "newspaper-type" headlines

Body

• Write in short sentences
• Write in short paragraphs.
• Frequent line breaks-–make the post more readable and keep people on-site longer
• Add bullets any time there's a listing of any sort. Always add jump links to any list.
• Add quotes from subject matter experts––this makes your content more authoritative and also makes it inherently viral. (Featured guests often share/link.)
• Conduct/include original research when possible. This is effective in building backlinks.
• Make sure images have alt text and include the primary keyword or related keywords

Code

• Use three dashes followed by the language, i.e. ```sql, to create code snippets that will be auto-formatted by our CMS

Sourcing

• Link to the primary source, even if the information was found through a secondary source
• Use in-line formatting for crediting sources. I.e. Hubspot does this well

Editing

After sending your completed draft, we will be doing three types of editing:

1. Copyediting: fact checking and typos
2. Substantive editing: higher level feedback with suggestions on which parts can be expanded or condensed to develop the storyline
3. Line editing: grammar, word choice, sentence flow

Thank you!

What you are attempting to do is incredibly difficult. One of the most difficult things there is, way harder than weight training, way harder, what you’re summoning, trying to summon within your brain and your spirit, to create something onto a blank page.  - Jerry Seinfeld, Tim Ferris Podcast

At Arctype we strive to create content for developers that inspires action, and this can be difficult at times.

But do not be discouraged! The key to writing is to start. Our editors will help you find the right words along the way.

If you want to submit your first post, you can follow the steps on our Writing for Arctype page to get started

Please email derek@arctype.com if you have any questions!

Happy writing!

The Arctype Team