Style Guide

This is the official Amplitude Developer Docs style guide. We offload most of the work onto Vale to keep the explicit style guide short, sweet, and accessible. We've found that engineers don't care about the minutiae of the English language as much as writers do, so we kept the official style guide as high-level as possible so our contributors only have to worry about the most important things.

📌 Expect this guide to change. The Amplitude Developer Center is maturing and this guide will evolve.

Audience for this guide

Anyone contributing to the Amplitude developer docs, primarily engineers, product, partners.

About Vale

---

Vale is a syntax-aware linter. We use it in the Developer Doc Center project to do the heavy lifting so we don't have to have a long, intimidating style guide.

If you are contributing to dev doc often, we highly recommend taking the time to install Vale locally. It is configured for our style guide, and flags style issues in your work. Learn more in the README.

The reason we have a style guide

---

A style guide keeps our voice and how we talk about our products consistent. Consistent docs foster trust from our customers because they learn how to find what they need. Consistent docs are reliable and trustworthy.

A style guide helps us write for a global audience, and helps keep the docs accessible. Writing for a global audience means that all readers can better understand our docs, and future translation will be cheaper, faster, and better. Global English is often more accessible. Simpler = better, almost always.

General writing tips

---

Keeping the 5 Cs in mind when writing for developer docs can quickly improve the quality of your writing:

• Clarity: Clarity makes sure your writing is easily understood by the maximum audience. Clarity lowers cognitive load and makes your docs (and by extension, product) seem easier to use.
• Concision: Being concise means you use the simplest terms and provide only the information your readers need. It means not adding every single detail about the product or feature into docs. If something has a lot of information that needs to be referenced, create a reference doc instead of cramming everything into the prose.
• Consistent: Consistency breeds trust in the company and the product. Consistency looks like using the same term/feature/label name throughout the doc. For example, don’t flip-flop between calling something URI and endpoint URL. Choose or follow a standard and stick to it. Consistency looks like following the established file naming conventions (for readable URLs), established formatting templates. Do not reinvent the wheel with each doc. Aim for consistency.
• Complete: Give all the information needed, but remain concise. For example: Don’t publish an SDK doc without all common initialization options documented.
• Correct: There is little worse than incorrect docs. Having NO documentation is better than having WRONG documentation. Make sure your docs are vetted for technical correctness by a peer or a SME.

General rules

---

Rule	Don't ❌	Do ✅
Use present tense.	You will see the code update.	The code updates.
Don't use directional language.	In the example below...	In the following example...
Use short sentences. Try to keep them under 30 words.
Use a single word when possible.	There are a number of ways to accomplish this task.	There are many ways to accomplish this task.
Avoid first-person pronouns.	When you perform this task, we then take the data and upload it to space.	When you perform this task, Amplitude takes the data and uploads it to space.
AM and PM. Capitalized, preceded by a space.	The job starts at 9am	The job starts at 9 AM.
Use sentence case in headlines.	How Amplitude Works	How Amplitude works
Avoid gerunds in headlines.	Setting up the thing	Set up the thing
Use contractions.	Do not add the values there.	Don't add the values there.
Spell out month names.	Run the job for Apr-Jun	Run the job for April through June.
Don't use ie or eg. i.e is in essence, which is just a way of rephrasing the point. If you find yourself wanting to use i.e, try rephrasing the sentence instead.	Enter the date in YYYYMMDD format, e.g. 20220101.	Enter the date in YYYYMMDD format. For example, 20220101.
Don't use passive voice unless necessary.	Export size for cohorts is limited to 10 million users.	The size limit for cohort export is 10 million users.
Don't use "since" when you mean "because"	Since there are millions of records in the queue, uploads can take a long time.	Because there are millions of records in the queue, uploads can take a long time.
Don't use "once" when you mean "after" or "when".	Once the upload is finished, close the window.	When the upload is finished, close the window. / After the upload is finished, close the window.
Don't refer to potential future functionality. As a public company, we want customers to make buying decisions based on current functionality. We can't say anything in the docs that can be construed as any promise.	Currently, only the wizzybop parameter is supported. In the future, Amplitude plans to add support for 8 other parameters.	The wizzybop parameter is supported.
If the doc discusses personal information, privacy, or security issues. Contact the Legal department for review.

Dummy tokens

---

Use these dummy values in code samples. If using a dummy value wouldn't be clear and you need a more demonstrative value in an example use the field name itself.

For example, when introducing a function in the docs:

Amplitude.instance().setUserId("userId") where a dummy "userId" value wouldn't be clear enough.

Token	Value
API Key	<API_KEY>
user_id	576dbce6-e2b7-11ec-8fea-0242ac120002
device_id	C8F9E604-F01A-4BD9-95C6-8E5357DF265D

Parameter tables

---

For maximum accessibility and to keep from having mess with more columns than necessary, we use a simple format for parameter tables.

Rule	Don't ❌	Do ✅
Optional, required. Type. Description. Defaults.	Specifies additional configuration options for the Ampli Wrapper. This field is optional. Default is false.	Optional. String. Specifies additional configuration options for the Ampli Wrapper. Defaults to false.

Wrap the term Optional in <span class="optional">, and wrap Required in <span class="required">. This adds the special formatting to the term.

Example table:

Name	Description
props	Optional. Integer. Set to 1 to include user properties in the response object.
propKeys	Optional. string[]. One or more user properties to include in the response. If left undefined and props=1, response object returns all available user properties.