Docs

Contents


Article Structure

Creating a scannable, neatly organized article is essential to keeping readers on task. Each Docs article contains the same content structure:

  • Title
  • Introduction
  • Table of contents
  • Body content

Guidelines

Titles

Create simple, specific article titles. Readers should have a clear idea of what questions are answered in the article.

  • Use title case, except for conjunctions and prepositions. “Price and Plans Guide” not “Price and plans guide
  • Capitalize the names of Help Scout-specific features. “Workflows, Beacon, Docs
  • Capitalize the names of third-party applications.
  • Avoid nouns, verbs, and adjectives ending in -ing. “Manage Account Security” not “Managing Account Security
  • Titles are always simple statements, never questions. “Edit Customer Profiles” not “How do I edit customer profiles?

Introductions

Article introductions let the reader know what the article contains, or what questions the article answers. Avoid sales pitches and funny catchphrases. If a feature is plan-specific, the introduction is a great place to mention which plan a feature is available on.

Table of contents

Table of contents provide the reader a quick way to find what they’re looking for. Create a table of contents for articles with 2 or more key points. Link each list item to its corresponding Header 3 text.

  • Use Heading 4 for the In this article title text.
  • List article sections using an unordered (bulleted) list.
  • Add anchor links to each bullet point.
  • Use this HTML to style the table of contents: <section class="index-list"></section>

Body content

Stay relevant, clear, and concise. Use as few sentences in a paragraph as possible, and try to avoid big words and long sentences. Use active voice, not passive voice. Add context using images to make content easier to understand.

Headings and sub-headings (H3, H4)

Additional headings help break up ideas and important concepts. Headings and sub-headings can be a little longer and more specific than article titles.

  • Use Header 3 for primary section titles. Use Header 4 for sub-headings under Header 3.
  • Headings and sub-headings also use title capitalization. “Write Them Like This” and “Not like this

Step based instructions

Definition lists are great for step-by-step instructions. Use definition lists when the primary purpose of the article is to explain how to complete a task in the app.

  • Steps should be in sentence and paragraph format.
  • Keep definition lists to 9 or less steps when possible.

Callouts

Callouts are small, styled text boxes that are ideal for calling attention to important reminders that you want the reader to remember. There are multiple callout colors available, but we only use yellow callouts within Docs articles.

<section class="callout-yellow">
  <h3>This is a yellow callout</h3>
  <p>Just add class="callout-yellow". It's really that easy.</p>
</section>

Images

Clearly cropped images help the reader get their bearings in the app. Use images sparingly, but don’t shy away from adding an image if its helpful.

  • Crop images neatly and proportionally.
  • Avoid large margins or areas of white space.
  • If you’re capturing images on a Retina display, scale down the image (size equally to 50%) before saving.
  • Avoid all annotations, such as arrows, shapes, and text.
  • Use the browser console to edit HTML on the page to make image content consistent. For example, images showing how to edit a User profile should show the same User name in each image.
  • Images are always aligned to the left, with no text wrap.
  • Save images as .JPEG or .PNG, make them a reasonably high quality.
  • Use an image optimization tool, such as ImageOptim to optimize images before uploading.

Lists and bulleted lists

Ordered (numbered) lists can be used to explain a series of steps or reminders that don’t require multiple actions or related images. Unordered (bulleted) lists are helpful for grouping together concepts or ideas.

Bold text

Bold text is reserved for highlighting specific call-to-action items. When writing descriptive text, use bold text to highlight the name of a menu item, link, or button.

“Click the Notifications link. Select your desired notifications, then click Save Notifications.”

Creating New Articles

Article slugs

Article slugs are part of the article URL. The article slug should match the article title, word for word.

Title: Manage Voice Messages
Slug: article/71-manage-voice-messages

Keywords

Keywords are terms or phrases that help boost an articles rank in search results. For example, if you write an article about forwarding from Gmail, you might use Google, Gmail, and forwarding as keywords for the article.

Start with a draft

Food for thought before you write:

  • Why are you writing the article?
    Defining the “why” before drafting the “how” helps identify puzzle pieces, and where they need to go when you start writing.

  • What is the purpose of the article?
    Think about what you want the reader to accomplish.

  • Who is reading the article?
    Think about which role the article calls to. Is the article meant for Users, Administrators, or both? Is the article for a new, potential customer or a seasoned User?

  • What does the article look like?
    Preview the article frequently as you write. Pay attention to formatting, paragraph structure, image placement, and overall length of the article.

Create specific content

Complex topics can require long explanations, but sometimes more specific content is more helpful. Break out long articles that cover multiple, related topics, in to separate articles when appropriate. On the flip side, long form content is helpful for things like Getting Started guides and knowledge clusters, where lots of relevant content is packed in to one article.

Proofread

Proof your article before publishing. Read it again, again, and again. Before publishing the final version, ask a teammate to read the article. Check for spelling, grammar and punctuation errors. Run the content through a service like Grammarly or Hemmingway as an extra proofreading step. Clean up extra HTML tags or spacing in the HTML editor.