Alexa Tech Docs Usage Dictionary

The usage dictionary lists terms and their usage guidelines; including spelling, capitalization, and style rules; that you should follow as you write Alexa Tech Docs content.

A| B| C| D| E| F| H| I| M| N| O| P| Q| S| T| U| V| W| Y|

A

Alexa
Amazon's cloud-based voice service available on tens of millions of devices from Amazon and external device manufacturers. With Alexa, developers can build natural voice experiences that offer customers a more intuitive way to interact with the technology they use every day. Acceptable to use Alexa service to differentiate the cloud service from the Alexa customerfacing voice user interface (VUI). Avoid the pronouns she and her. Alexa doesn't have a gender. For more details, see Alexa Skills Marketing Guidelines / Alexa and gender.
Alexa app
The companion app for Alexa customers to set up devices, change settings, and view the displayed output from interactions with Alexa. Don't capitalize the a in app. Don't use application.
Alexa Built-in
Term used in Alexa Voice Service (AVS) content to refer to Alexa-enabled devices built by external developers.
Alexa cloud
Don't use. See Alexa and Alexa Voice Service.
Alexa-enabled device
The Alexa device category that encompasses all Echo devices, and any third-party devices. See also Echo device with a screen. [Accepted and adopted by Consumer Support.]
Alexa-enabled device with a screen
The Alexa device category that encompasses Echo Show, Echo Spot, and any other first-party or third-party devices with a screen. See also Echo device with a screen. [Accepted and adopted by Consumer Support.]
Alexa Everywhere
Don't use. This is the name for the Amazon internal team previously known as Alexa 3P.
Alexa Skills Store
Amazon's online marketplace to purchase Alexa skills. Use initial capitalization on first use. The term Skills is always plural in the name. You can shorten to store after first use in a page, as long as you are clear to developers what store you refer to. Not to be confused with Amazon Appstore.
Alexa Voice Service
An Alexa service that enables external software and hardware developers to access cloud-based Alexa capabilities with the support of specific APIs, hardware kits, software tools, and documentation. Don't confuse with Alexa Skills Kit, which is a collection of APIs, tools, and documentation to provide Alexa with new capabilities. After first use per page, you can abbreviate to AVS.
Amazon Appstore
Amazon's online marketplace to purchase apps compatible with the Android operating system. Appstore is one word. Not to be confused with Alexa Skills Store.
Amazon Polly
Use initial capitalization. A service, separate from Alexa, that turns text into lifelike speech, allowing you to create applications that talk, and build entirely new categories of speech-enabled products. Amazon Polly is a text-to-speech service that uses advanced deep learning technologies to synthesize speech that sounds like a human voice. With dozens of lifelike voices across a variety of languages, you can select the ideal voice and build speech-enabled applications that work in many different countries.
ampersand (&)
Avoid in all text outside of code. See also Titles and Headings.
application programming interfance, API
Use to refer to the entire set of operations, types, inputs, and outputs for a service. Don't use to refer to specific operations within a specific API. Follow the API capitalization standard set by ASK Marketing. Capitalize the names of API collections, unless Amazon has standardized the API collection name as always being lower case. With skill API names, use the singular Skill, not Skills.

Alexa Tech Docs style:
The Skill Simulation API is an asynchronous API that simulates a skill execution.
If your skill is a custom skill, you can add support for Echo Buttons by using the Echo Buttons Skill API.
The Smart Home Skill API communicates with your skill adapter using a JSON message format.
The Video Skill API is available at the same top level that Alexa uses to build video experiences on Fire TV.
app, application
Don't use to refer to skills. See also Alexa app.
Amazon Standard Indentification Number, ASIN
An Amazon Standard Identification Number (ASIN) is a unique block of 10 letters and numbers that identify an item. Spell out on first use in a page if your audience might be unfamiliar with the acronym. You can find the ASIN on the item's product information page at Amazon.com. For books, the ASIN is the same as the ISBN number, but for all other products, Amazon creates a new ASIN when the item is uploaded to the Amazon catalogue. You can find an item's ASIN on the product detail page alongside further details relating to the item, which might include information such as size, number of pages (if it's a book) or number of discs (if it's a CD).

Alexa Tech Docs style:
The ASIN for Hasbro's Monopoly game is B00005N5PF.

B

Boolean
Boolean values are true and false. Avoid using a Boolean value name at the beginning of a sentence or sentence fragment. For specific programming languages, follow the usage and capitalization in the language.

C

can, could, may, might, must
Don’t use could for can unless you’re referring to the past. Avoid using can or may. Can implies ability but not action. Rewrite to describe the action. When ability is what you need to express, it's OK to use can to describe actions or tasks that the reader or program is able to do. May can mean either permission or possibility, which is ambiguous. In most cases, you can replace with might to mean possibility.
capitalization
See Capitalization under Use of Language.
consumer
Don't use. See developer, customer.
customer
Use customer in cases where you refer to the end user of the skill in purchasing decisions and workflows, when the end user is the Alexa account holder. In all other end-user contexts, use user. When you refer to the developer audience, in most cases use you. See also user, end user.
customer experience, CX
Don't use. Jargon. Rewite to avoid introducing these terms into your content.

D

developer
In most cases, write directly to the audience or replace with the more direct form you. Reserve developer or skill builder for cases where you need to refer to your audience in the third person. Don't shorten to dev. Don't use skill developer. See also user, customer.
developer console
Don't capitalize. The generic name for the web-based collection of tools for external developers to build Alexa skills, Alexa Voice Service Alexa-enabled devices, Amazon Appstore apps, or Amazon Dash devices and apps. To distinguish between different developer consoles, capitalize the name of the console, followed by developer console. For example, Alexa developer console, Appstore developer console, etc. Developers access the various developer consoles through the developer portal.
developer portal
Don't capitalize. The colloquial name for the Amazon Developer Services and Technologies website at https://developer.amazon.com/home.html. Avoid referring to it if possible. Instead, refer to the developer console, Alexa Skills Kit, Amazon Appstore, or another more specific developer website.
dialog
Use "dialog" when you describe a conversation between Alexa and an end user. Don't use "dialogue." Also, use "dialog box" not "dialogue box" to describe the user interface (UI) element.

E

easily
Don't use. Be careful to avoid implying that a task is fast or easy. These are subjective judgments that readers could construe as Amazon guaranteeing a particular outcome.
Echo device with a screen
The Amazon Alexa category that encompasses Echo Show, Echo Spot and any other Echo devices that have a screen to display a graphical user interface (GUI). See also Alexa-enabled device with a screen. [Already used by Consumer team.]
ecosystem
Don't use. For example, don't write, Alexa ecosystem. See also Alexa.
ensure
Don't use. Instead, use "make sure."
enter
Use to instruct the developer to type or otherwise insert a value. Don’t use type.

Alexa Tech Docs style:
In the search box, enter Alexa Skills Kit.
example, code example
Term that refers to a collection of code in your content. Don’t use snippet. Don't confuse with sample. See also sample.

F

fast
Don't use. See easily.
first party, 1P
Don't use. Instead, use Alexa-enabled devices or Echo devices to refer to internal built devices. See also Alexa Everywhere.
feature names
New service, feature, and resource names created by product teams must be reviewed by the marketing and legal team before you can use them in public-facing content. Names can be descriptive, suggestive, arbitrary, or fanciful. They can include Alexa, Amazon, or neither. If you have concerns about a proposed name, contact your editor or the legal team. Follow the capitalization and spacing approved by marketing and legal. Avoid using any variation of an internal code name in public facing content, including API actions or graphic file names. Use approved feature names conservatively. Avoid using overly branded terms. Instead, focus on descriptions that explain what the item is. See also Legal Requirements.
Flash Briefing
Use initial caps. An Alexa capability that delivers customized news and content to users from popular broadcasters, local weather services, and more. Some providers have video available to play along with the audio on compatible devices. [Approved for use in Consumer content]

H

hands free (n), hands-free (adj)
Any technology that the user controls by input other than hands or fingers. For example, body movement, eye movement, or voice are hands-free inputs. Don't use to mean voice intiated, which is a more specific input technology.
hyphens
See hyphens under Punctuation.

I

in order to
Don't use. Unecessarily wordy. Shorten to just to.

M

market
Don't use. Instead, use marketplace, region, locale, or geogrpahy.
marketplace
A marketplace is a place, physical or otherwise, where merchants offer goods for sale, and customers accept offers, place orders and make purchases. It is the logical container for all data and attributes associated with an e-commerce site. A marketplace is identified by a globally unique MarketplaceId. For more information, see the Marketplace entry definition on the Amazon wiki.
measurement
See Units of measurement under Use of Language.
monetize, monetization
Don't use. These terms are jargon. Replace with a specific description of the developer objective or task. Use verbs such as "buy," "sell," or "purchase." For example, "In-skill purchasing lets you sell premium content, games features, and intuitive stories in skills with a customer interaction model."
multimodal
One word, don't hyphenate. Computer-user interaction that involves more than one modality, such as a combination of speech, touch, and graphics.

N

Node.js
One word. Don't use "Node" to mean "Node.js," and don't lowercase the "N" in "Node.js."
note that, note the
Don't use. Unnecessarily wordy. Usually you can just remove these terms without harming meaning. If the reader benefits from drawing attention to the statement, put it in an alert or callout. See also alerts and callouts.
numbers
See Numbers under Use of Language.

O

OK
Use OK, all caps. Don't use O.K., ok, o.k., okay, or all right. Never use alright.

P

platform
Don't use to refer to Alexa (i.e., "Alexa platform"). See also Alexa and ecosystem.
please
Avoid. Only use the term "please" when you are asking the developer to perform a task that isn't convenient or is required due to the error or fault of the software or website.
preconfigured
One word, no hyphen. To set up ahead of time. It implies that the device or software application has been modified to suit the customer or situation.
punctuation
See Punctuation under "Mechanics."

Q

quotation marks
See Quotation marks under "Punctuation."

S

sample, code sample
Term that refers to code projects that can be fully compliled and are available on GitHub. Don't confuse with example. See also example.
simply
Don't use. See easily.
second party, 2p
Don't use. Refers to other Amazon businesses or services outside of Alexa. For example, Amazon Music, or Amazon Video. See also Alexa Everywhere.
set up vs. setup
Set up is a verb and setup is an adjective or noun. Don’t use set-up.

Alexa Tech Docs style:
Set up account linking.
The tutorial setup can take about 15 minutes.
The Alexa setup process helps customers learn about Alexa and sign in to their Amazon account.
skill
Always lowercase skill, except in a name like Alexa Skills Store. Don’t refer to a skill as an app or application. When you refer to a developer creating a skill, the skill is created one at a time, so use the singular (skill). The exception is when you refer to more than one skill that falls into an API category. In that case, use the plural (skills). With skill API names, use the singular Skill, not Skills.

Alexa Tech Docs style:
You can build a flash briefing skill by using the Flash Briefing Skill API.

See also Alexa Skills Store, API.
skill connections
Lowercase. The overall services and configuration that support directly connecting a skill (a requester) to other functionality (a provider) for the purpose of giving the customer extended functionality while in the skill. Use "skill connections" or "skill connection" when referring to or describing implementation of a skill connection.
smart TV
Lowercase "smart," uppercase "TV." A TV set that is internet-enabled and can stream media such as music, movies, and photographs. Some smart TVs include a browser to surf the internet, or enable users play games and use other other applications.

T

then
In If…, then… constructions, remove then, except for code constructs in code examples.

Alexa Tech Docs style:
If your dogs are hungry, feed them.
When your dogs are hungry, feed them.
third party, 3P
Don't use. Instead, use you, developer, or skill builder. See also Alexa Everywhere, partner.
this
Avoid. The pronoun this is often ambiguous as to what subject or object it refers. Write around the term or be more specific.

Not Alexa Tech Docs style:
AWS Lambda and this pass playback lifecycle events and the metadata of the current content to Alexa.
Alexa Tech Docs style:
AWS Lambda and the JavaScript library pass playback lifecycle events and the metadata of the current content to Alexa.
-Or-
Alexa Tech Docs style (if the context is clearer):
AWS Lambda and the library pass playback lifecycle events and the metadata of the current content to Alexa.
try to
Use try to, not try and. While try and is no less grammatically correct, use try to for global consistency and clarity.
type
See enter.

U

use case
Avoid. The term is often jargon. You can usually remove it without affecting the meaning of the sentence.
user, end user
In most cases where you refer to the developer’s end user, use user. Use customer in cases where you refer to the end user of the skill in purchasing decisions and workflows. Don't use end user. Don't use user to refer to the developer. See also developer, customer.
utilize
Avoid. This term is jargon. Substitute use instead.

V

voice first, voice forward
Avoid. These terms are jargon and vague. Write around these terms or explain.

Alexa Tech Docs style:
You must meet certification guidelines for creating an experience designed for voice.
voice initiated (n), voice-initiated (adj)
Any technology that a user can control by voice input. For example, an Echo is a voice-initiated device. Don't use to mean hands free, which is a more general input technology.

W

wake word enabled
Any technology that a user activates by saying a specific, predefined word followed by a question or command to generate a response. Don't confuse with voice intiated or hands free.
we
Avoid. Condescending and counter to Amazon style. Focus on the customer, and try not to make Amazon the subject. In sentences where a recommendation is made, write, Consider…,. [Blah] is the best way to [blah]…, or just use the imperative. As a last resort, you can write, Amazon recommends….

Alexa Tech Docs style:
Consider testing your skill prior to submitting it.
Alexa Skills Kit is the best way to build Alexa skills. (Instead of We recommend that you use the Alexa Skills Kit ….)
Test your skill prior to submitting it.
will, shall
Don't use. Use present tense. Future tense is only acceptable in rare cases, to avoid reader confusion. See also Verbs.

Y

you only need to (or similar)
Avoid. Confusing and ambiguous. Try to reword to clarify if the action is required or optional.


Back to top