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.
Creating a scannable, neatly organized article is essential to keeping readers on task. Each Docs article contains the same content structure:
- Table of contents
- Body content
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?”
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
A table of contents provides the reader a quick way to find what they’re looking for. Create a table of contents for articles with two or more key points. Link each list item to its corresponding Header 3 text.
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. Always use an Oxford comma when making lists.
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.”
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 nine or fewer steps when possible.
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.
<h3>This is a yellow callout</h3>
<p>Just add class="callout-yellow". It's really that easy.</p>
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 it’s 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 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.”
To call out a contact us in an article, use the link to the contact modal rather than a mailto: link with our email address. The a tag for this is:
<a href=''#contactModal' data-toggle='modal' class='contactUs'>
Article slugs are part of the article URL. The article slug should match the article title, word for word.
Title: Manage Voice Messages
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.