Product Content Guide

A few things to help us in creating product content at AgencyBloc. Product content is any content that is in the app or describes/helps a user with the app.


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. Review with a peer. 
  • Draft - Write a draft.
  • 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.

Collaboration: 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, select… Select [this option] to export contacts
Avoid the passive voice when possible Filter search results by... Search results 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

use utilize

Avoid unnecessary modifiers

Accessible

Guideline  Do Don't
Avoid directional terminology when possible Select the Profile & Settings Icon Click at the top right corner...
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 or more serious.

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, you can
Foster user success Good job!

Terminology

Terminology is our shared vocabulary and 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 Select 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

Vocabulary List [needs review]

Do Don't
app, application System
 app sections, app area Landing Pages
Main Menu, navigation Main tabs
Secondary Menu main tabs
Select Click
Associate/Connect
Save
Delete
Update
Record Actions
Relationships Relations
Individual Summary Rollup

Convention & Grammar

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

Capitalization

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

Numbers [needs review]

Guideline  Do Don't
Spell out a number when it begins a sentence. Otherwise, feel free to use the numeral. This includes ordinals too.
Numbers over three digits get commas.
Generally, spell out fractions.
Use decimal points when a number can’t be easily written out as a fraction
In articles, default to not using 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 Select 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
Never use capital letters for emphasis LOUD NOISES
Don’t combine emphasis techniques Important
Don’t use underline

Content Types & Structure

Content structure provides consistent flow and expectations for readers.

Short Form: Interface copy, error message, success message, labels

Guideline: Be concise and precise. Just enough content to be clear.

  • Labels: 1-3 words
  • Copy: 7-11 words

Medium Form: App messages, alerts, error messages, tips, empty states, in app marketing

Guideline: Focus content on the situation and context to solve a specific user problem.

  • Title/Heading
  • Description
  • Forward Path (link to help or area in app)

Long Form: Help articles & guides, release notes, app marketing pages

Guideline: Organize around one central topic. Use clear, descriptive words to convey the topic in titles and headings and sections.

  • Title
  • Introduction/Overview
  • 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. Product content should easily readable and digestible so users can easily gain understanding to complete desired tasks. 

Use the following tools to validate:

Guidelines:

  • Shoot for Grade 7-8 or lower
  • Read time under 3-5 minutes
  • 1-3 hard sentences
  • 0-1 very hard sentences

Images, GIFs, Videos

What to Use When

Images - Demonstrate location of an item/topic on a single page
GIF - Demonstrate simple interactions or movement on a page - Demonstrate simple interactions or movement on a page
Video - Demonstrate multi-step processes across multiple sections, limit to 2-3 minutes

Guideline

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.
  • 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.