Writing Style
General Guidelines
The that we follow in our visual language also apply in our verbal language. In some cases, verbal content communicates even more information than visual cues. For example, the text of an error alert informs the user about why the error occurred and how they can resolve the error. While these guidelines come from standard stylebooks and writing recommendations, please feel free to adapt them to suit the situation.
Communicate with clarity.
Use short words, direct statements and common terms. Avoid technical jargon. Add tooltips or links if they help.
Use active voice for verbs. Active voice makes text easier to read by identifying a clear agent and clear actions to take.
Describe choices as "positive" actions when possible, especially when it is a binary choice.
Keep it simple. Keep it short.
Be concise and precise. Write only what is absolutely necessary.
Consistency is the hallmark of well-built systems.
Use spelling, grammar and syntax consistent with the appropriate language and region. American English is our system default.
Capitalize only the first word (sentence case) for titles longer than four words (e.g., content headings). Capitalize words longer than three letters (title case) for titles four words or shorter (e.g., buttons).
When describing a set of options or potential outcomes, use parallel sentence structure to make the choice clear.
Respect important information.
Place important information first.
Spell out acronyms and abbreviations when you first use them on a page. Never assume prior knowledge.
By default, the Single Sign-On (SSO) feature is enabled. Disable SSO for custom domains by clicking the button.
Use numerals for numbers and symbols for units where applicable. They stand out in the middle of sentences and leave less room for ambiguity.
You have used 20% of your storage.
This product has 0 users.
Hyphenate compound adjectives to make single concepts clear. A label platform is not white; a platform is white-label.
One-Time Purchase
White-Label Platform
Proofread. Repeat.
To avoid common mistakes, verify terms in a dictionary. The built-in Dictionary app on Mac OS X provides common spellings, regional variations, and usage rules and examples.
Terminology
This section attempts to define and elucidate common terms in the AppDirect UI.
| Term | Definition and Rules |
|---|---|
| AppDirect | "AppDirect" is one word. It must be on the same line; do not separate or hyphenate. Never abbreviate (e.g. AD, AppD, etc.). |
| Marketplace | A branded system that connects software vendors to buyers. Often labeled as "Channel." |
| Vendor | A company that sells a product in a marketplace. Vendor-facing UI often uses "Developer" instead. Never use "ISV." |
| Product | An item sold in a marketplace, including Applications (Apps), Bundles (of Applications), Add-On's, etc. Vendor-facing UI often uses "Subscriptions" to describe products with recurring charges. Paid products may charge recurring fees or a one-time fee (labeled with "One-Time Purchase" status). |
| Application | The primary component of a Product. Preferable to "App" but you can use "App" for variation after the first use. |
| Bundle | A Product that is a collection of Applications and/or Add-Ons. |
| Add-On | A secondary component that users can choose to add to their Product, such as a feature or additional storage. In legal contexts, Add-On's refer to additional integrations that marketplaces can add to the core product, such as billing integration, CRM (Customer Relationship Management) and Developer Center. |
| Edition | A pricing plan for a Product that determines the fees charged to the user and the billing frequency. |
| Company | May refer to either a company that purchases a product or a company that sells a product. In legal contexts, the "Company" is always the marketplace partner. |
Common Mistakes
Set up, log in, sign up, etc. are examples of phrasal verbs. By contrast, setup, login, sign-up are nouns or adjectives.
Sign up for AppDirect
You have not completed your account setup.
Use because to describe causal relationships, not since. Since means "from the time when."
This user is inactive because she has not logged in for six months.
This user has not logged in since six months ago.
That and which refer to places and things, including groups and companies, while who refers to people. You can use whose for both people and inanimate things.
The marketplace that requested this product has not added it yet.
The administrator who purchased this product has not added any users to it yet.
Less describes uncountable things while fewer describes countable things. One exception is less than, which you can use with numbers.
Fewer users
Less than 5 products