Help Writing Guide

A few things to direct us in creating help content at AgencyBloc

  • Process
  • Voice
  • Tone
  • Terminology
  • Convention & Grammar
  • Structure
  • Readability
  • Images

Process

To create better content faster, we'll follow this process. Of course, sometimes the exception proves the rule :-)

  • Strategize -  Determine a clear purpose/objective to help your focus.
  • Research - Be curious. Ask. Listen. Read. Dive into the subject matter.
  • Organize - Draft a brief outline - by category and article. Review with a peer. 
  • Draft - Write a draft in Google Docs.
  • Proofread - Separate proofreading from writing; it's faster and more effective that way.
  • Review & Revise -  Review and revise in tandem with a peer. 
  • Upload & Format - Load into CMS and follow patterns in the style guide, help article formatting to make content consistent and digestible.

How to: Use basecamp to track items to loop people in. Also, use commenting in google docs.


Voice

Voice is our identity that drives what and how we communicate. Using a consistent voice builds trust, familiarity, and makes content more meaningful and easier to consume for readers.

Direct

Guideline  Do Don't
Address the user You can… AgencyBloc can…
Focus on what the user can do rather than what AgencyBloc can do for the user  Choose from four options This setting has four options
Lead with the user's tasks To export contacts, click…
Avoid the passive voice when possible Filter orders by Orders can be filtered by…

Clear

Guideline  Do Don't
Avoid cliché and subjective language robust, easy
Avoid jargon
Avoid overly complex word selection or phrasing

Concise

Guideline  Do Don't
Omit needless words You can adjust…
You can manage
There are three user types
You have the ability to adjust…
You'll be able to manage…
There are three different user types
Chunk and limit paragraphs

Use short words and sentences

Avoid unnecessary modifiers

Accessible

Guideline  Do Don't
Avoid directional terminology when possible Select the Profile & Settings Icon Click at the top right corner of AgencyBloc
Avoid referential language relying on space or device Select from these options (list options) Select from the options listed on the bottom of the page.
Use descriptive links Read more in the Managing Security Groups article Read more by clicking here.
Use concise Alt Text Your Personal Dashboard This is a picture of what you see when you log in to AgencyBloc

Tone

Tone is how our voice responds based on the situation and/or audience: more lighthearted in the Release notes, more serious in API documentation.

Conversational

Guideline  Do Don't
Use plain English use utilize
Avoid overly playful language We'll get back to you as soon as we can! We'll get back to you lickety-split!
Contractions are OK It's It is

Positive

Guideline  Do Don't
Present AgencyBloc in a positive light AgencyBloc supports AgencyBloc only supports
Write in an affirmative voice when possible Full Users can You can't
Write apologetically when necessary Sorry! Email campaigns does not allow No attachments in email campaigns.

Cultivating

Guideline  Do Don't
Help users be successful You can do this .... to help you in this... AgencyBloc supports
Provide specific insights and ideas During open enrollment
Foster user success Good job!

Terminology

Terminology is our shared vocabulary the helps us communicate consistently. 

Guideline  Do Don't
Use terminology as written in the app
Label UI elements (e.g., button, drop-down menu) only when needed for clarity Click Save Click the "Save" button
Write phrasal verbs as two words Log in here Login here
Write compound nouns/adjectives as one word login credentials log in credentials

Convention & Grammar

Convention and grammar keep our content in check to make sure writing habits are consistent across all content produced.

Capitalization

Guideline  Do Don't
Use title case in article titles, section headers, and when referring to features
Don't capitalize common nouns unless they're in a title
Capitalize and space integration partner names exactly as our partners would

Numbers

Guideline  Do Don't
Spell out a number when it begins a sentence. Otherwise, use the numeral. This includes ordinals, too.
Numbers over three digits get commas.
Spell out fractions.
Use decimal points when a number can’t be easily written out as a fraction
Don’t use the % symbol. Spell out the word “percent.” ???
Use a hyphen (-) to indicate a range or span of numbers.

Punctuation

Guideline  Do Don't
Use only one space after a period This is a sentence. This is another one. This is a sentence.  This is another one.
Omit apostrophes when pluralizing acronyms/initialisms APIs API's
Use the serial comma This product has three attributes: size, color, and style.  This product has three attributes: size, color and style
Use the chevron symbol to show navigation Individual > Activities Individual -> Activities

Emphasis

Guideline  Do Don't
Use bold text when referring to buttons Click Save Click the "Save" button
Never highlight an entire sentence in boldface text Never highlight an entire sentence in boldface text Never highlight an entire sentence in boldface text
Never use capital letters for emphasis LOUD NOISES
Don’t combine emphasis techniques Important
Don’t use underline

Structure

Content structure provides consistent flows and expectations for readers. Organize an article around one topic. Use clear, descriptive words to convey the topic in titles and headings.

Typical Article Outline

  • Title
  • Introduction/Overview
  • Covered in this article (article outline)
  • Body content (broken into smaller sections)
  • Related Links

Readability

Readability is how easily an article is scanned and/ or read. Help content should easily readable and digestible so users can easily gain understanding to complete desired tasks. Use hemingwayapp.com to validate. 

Guidelines:

  • Shoot for Grade 9 or Lower
  • Read time under 3-4 minutes
  • 1-3 hard sentences
  • 0-1 very hard sentences

Images

Images illustrate and demonstrate concepts where simple text would be insufficient. Use images to provide context, sequence, and orient readers.

  • Focus in as closely as possible to only capture what is needed.
  • Use a clean demo account with appropriate data volumes for examples. 
  • Remove unnecessary in-app details when you can
  • Clear in-app notifications. Collapse filters that aren’t relevant to the screenshot. Hide extraneous details
  • Properly frame the subject

Guiding principles: What's the most helpful context? Capture this. What isn’t helpful? Crop it out or hide prior to capture. Use browser zoom to produce a fuller, more crisp screenshot.