Parse.ly’s Documentation Style Guide

This style guide provides writing rules and guidelines specific to Parse.ly documentation. Anything not covered here is governed first by the WordPress VIP Documentation Style Guide, then the WordPress Documentation Style Guide, and finally the Chicago Manual of Style.

This is a living document — changes and updates will be made as Parse.ly’s documentation evolves.

Voice

Be concise.
Prefer active voice and direct imperative commands. When instructions can be stated as commands, omit “you can.”
Example: ~~You can access your account settings by clicking the gear icon.~~ Click the gear icon to access the account menu.
Use American English for spelling and punctuation styles, or consider using a different word that doesn’t have a different spelling in other English variants.
Use sentence case (not title case) for docs titles and subheadings.
Example: “Installation resources” rather than “Installation Resources.”
Avoid “we,” “us,” etc. when referring to the Parse.ly team. Instead, use “Parse.ly.”
Example: ~~We provide metrics on content performance.~~ Parse.ly provides metrics on content performance.

Pro Tip

The audience may have no experience with the Parse.ly Dashboard, or they may be long-time users. Speak to both, providing clear instructions and expert guidance.

Terminology

Parse.ly brand

Correct	Incorrect
Parse.ly	Parsely
Parse.ly API	Parse.ly api
Parse.ly Dashboard (Dashboard on second reference on a page)	Parse.ly Dash, Parse.ly dashboard
Parse.ly Data Pipeline	Parse.ly data pipeline
Parse.ly Support	Parse.ly support
Content Intelligence, PCI	Content Helper, PCH, etc.
Engagement Boost	Traffic Boost
Headline Testing (feature), headline test (action)	headline testing, Headline Test
Video Tracking, Content Conversions (and other feature add-ons)	video tracking, content conversions

Parse.ly Dashboard

Correct	Incorrect
account menu	account silhouette icon
alert	Alert, notification
factoid(s)	Factoid(s), any other naming
gear icon	cog icon, gear
navigation bar	nav bar, Nav Bar
Network Rollup	network rollup
page view	pageview
Sentiment Headline	sentiment headline
Site ID	site ID
top bar	Top Bar
network, publisher, site, author group, etc. (general terms — not Dashboard locations)	Network, Publisher, Site, Author Group

Note

The schema field and technical event type are spelled pageview (action = 'pageview') since they are technical field names.

When referring to the event type or technical implementation, use pageview in code formatting (e.g., “the pageview event”, “send a pageview“).
When discussing the concept generally in prose without referring to the technical implementation, use “page view” as two words (e.g., “analyze page views,” “each page view is recorded”).

The same applies to videostart events.

Definitions

Term	Definition
user	A team member who has access to and uses the Dashboard.
visitor	An individual who views a website page.
Dashboard (capitalized)	The Parse.ly product. Used in product name: “Parse.ly Dashboard.” On second reference, use “the Dashboard” with definite article.
dashboard (lowercase)	General concept of an analytics interface.
factoid	A single data point or metric displayed in the Parse.ly Dashboard (e.g., page views, engaged time). Always lowercase except when part of a specific feature name.
feature add-on	Optional Parse.ly features available for purchase (Video Tracking, API, Segments, Conversions). Always capitalize as proper nouns.
Network (capitalized)	Specific Dashboard location or Network Rollup feature.
network (lowercase)	General concept of multiple sites or properties.

Usage

A first reference to a specific, named Dashboard location or tool uses the full name plus a descriptor when needed. Subsequent references on the same page may be abbreviated for brevity, as long as consistency is maintained.
Example: “Parse.ly Overlay bookmarklet.” (First reference.) “Overlay.” (Second reference.)
A first reference to a Dashboard tab uses the tab name plus “tab.” Subsequent references on the same page use only the capitalized tab name:
Example: “The Overview tab displays top performing content.” (First reference.) “The layout of Overview can be customized.” (Second reference.)

Capitalization

Note on parent style guides

Parse.ly product and feature names are proper nouns that override the sentence-case preference in the WordPress VIP and WordPress Documentation style guides. This section clarifies when capitalization is required.

Capitalization hierarchy

Parse.ly uses the following hierarchy for capitalization:

Product names: Title case (Parse.ly Dashboard, Parse.ly API, Parse.ly Data Pipeline, Parse.ly Content Intelligence, Parse.ly Sage)
Feature names: Title case (Video Tracking, Headline Testing, Network Rollup, Content Conversions)
UI elements: Lowercase unless part of a proper feature name (gear icon, navigation bar, account menu)
General concepts: Lowercase (network, site, publisher, user, visitor, dashboard)
Acronyms: Maintain standard form (API, PCI, URL)

Product and feature names

Capitalize Parse.ly product and feature names as proper nouns. Lowercase when referring to the action or general concept.

Correct	Incorrect
Headline Testing helps optimize content.	headline testing helps optimize content.
Use Video Tracking to measure engagement.	Use video tracking to measure engagement.
You can headline test up to five variants.	You can Headline Test up to five variants.
Parse.ly tracks video engagement metrics.	Parse.ly Tracks video engagement metrics.

Dashboard locations and UI elements

Tab and page names are treated as proper nouns within the Parse.ly Dashboard. Capitalize specific tabs and pages, and named Dashboard locations. Use lowercase for general concepts.

First reference to a Dashboard tab uses “tab.” Subsequent references use the capitalized tab name alone.

Correct	Incorrect
The Overview tab displays top content.	The overview tab displays top content.
The layout of Overview can be customized.	The layout of overview can be customized.
Navigate to the Posts tab.	Navigate to the posts tab.
View all posts in your network.	View all Posts in your Network.
Filter by author, section, or tag.	Filter by Author, Section, or Tag.

Pro Tip

If it’s a clickable destination or named section in the Dashboard, capitalize it. If it’s a general concept, use lowercase.

General Concepts

Lowercase general terms and categories.

Correct	Incorrect
Filter by author, section, or tag.	Filter by Author, Section, or Tag.
Your network includes multiple apikeys.	Your Network includes multiple apikeys.
All users can access reports.	All Users can access reports.

Acronyms

Acronyms remain in their standard form even in sentence case.

Correct	Incorrect
Parse.ly API	Parse.ly api
Use the API endpoint.	Use the api endpoint.
Content Intelligence, PCI	Content Intelligence, pci

Headings

Use sentence case (capitalize only the first word and proper nouns).

Example: How to configure video tracking ~~How To Configure Video Tracking~~

Technical Conventions

Numbers

Spell out one through nine. Use numerals for 10 and above. Always use numerals with units.

Correct	Incorrect
Three metrics are available.	3 metrics are available.
The Dashboard displays 12 posts.	The Dashboard displays twelve posts.
Wait 3 seconds for data to load.	Wait three seconds for data to load.

Dates and times

User-facing docs: Month DD, YYYY
Example: The feature launched on January 15, 2024. (User-facing)

API docs: YYYY-MM-DD
Example: published_date: 2024-01-15 (API)

Code and technical terms

Use backticks for inline code, endpoints, parameters, and technical values.

Example: Set the apikey parameter to your Site ID.

Example: Call the /analytics/posts endpoint.

Use code blocks for multi-line examples.

URLs

Present URLs without backticks: https://docs.parse.ly/

Lists

When to use lists

Bulleted lists: Unordered items, features, options

Numbered lists: Sequential steps, prioritized items

Punctuation

Complete sentences: Use ending punctuation.

Example: The Dashboard provides metrics. It tracks page views and engaged time.

Sentence fragments: No ending punctuation.

Example:

Page views
Engaged time
Scroll depth

Maintain parallel structure across list items.

Screenshots

Pages that explain Dashboard tabs and tools should generally begin with a screenshot that allows a reader to orient themselves. Screenshots should show enough detail to make locations and steps obvious without overtaking the page.

When annotating screenshots, default to purple (#8a51ff). For Dashboard pages using purple in graphs and data, use red (#f93441) for screenshot annotations.

Set screenshots to center alignment and full-size resolution. Add descriptive captions and alternative text. Link each image to the original image file, enabling visitors to click the screenshot to see it full-sized.

Screenshots can be of the Dashboard in light or dark mode — a mix is preferred.