guides/Expo Documentation Writing Style Guide.md
The Expo documentation is the single source of truth for all implementations and usage of Expo SDK with tooling and related services. It evolves continuously with new features and services.
This style guide provides editorial guidelines for writing clear and consistent Expo-related documentation. Aim for clarity, accuracy, and completeness when contributing to the documentation with improvements. Use this style guide as a reference document for specific questions.
This page is divided into two main sections:
The "General" documentation contains all mechanics and formatting guidelines that we follow when writing Expo documentation.
All Expo documentation is written in Markdown.
Developers reading the Expo docs shouldn't find obvious mistakes and feel less confident in Expo. Write with correct grammar, punctuation, and spelling.
Always show and don't tell. Instead of explaining a concept to the reader, give them an example. Providing examples helps grab the reader's attention.
Some words have multiple legitimate ways to spell them. One of the most notorious examples in the Expo codebase is "canceled" vs. "cancelled". We tend to write "cancellation" instead of "cancelation". Prefer "canceled" and "canceling".
Developers read documentation to find answers to their problems. Documentation exists because it can translate complex information into easily digestible pieces. Voice and tone directly influence the translation of complex information and remove any friction.
Writing clearly and concisely using plain American English is the approach we take at Expo. We also use curb-effect when approaching technical documentation. We aim for clarity for all English speakers.
Generally, we prefer to write in the second rather than the first person. Use "you" instead of "we".
The word "we" is reserved when "we" as the Expo team directly want to interact with the audience or convey an important message.
Writing in the present tense allows our audience to understand the current benefits of our offering. Developers already face complex tradeoffs when selecting their stack.
Avoid writing sentences in the passive voice. Common passive voice usage uses words such as "was" or "by". Use Hemingway or Grammarly to check your passive voice usage.
Write short sentences. One thought per sentence is punchier and pithier. When you try cramming multiple thoughts and ideas into a single sentence, your copy becomes painful to read.
Use action verbs and subject verb-object construction, cut clunky phrases, and avoid jargon. Remove any adjectives or adverbs that don't modify the meaning of a sentence.
If you have to write a long sentence, follow it up with a short one. This can snap the reader back to attention. Don't repeat the same word in the same sentence. Furthermore, don't start or end a sentence with the same word you used to start or end the previous sentence.
Use "they" that can be used as a singular pronoun. When necessary, address a group of readers as "developers" or "app users".
When it is correct to use words instead of symbols:
When referencing multiple app stores, use "app stores" as a general indicator without capitalization.
When referencing a specific platform app store, use "Apple App Store" or "Google Play Store" (with capitalization).
The words "app" or "application" are used interchangeably since we use both at different places. However, use "app" or "application" when generally referring to an .ipa, .apk or .aab file.
Use ".ipa" or ".apk" or ".aab" only when referring specifically to that extension.
Before an app is built into an app archive, it is a project. For example, "EAS Build takes a project and produces an app".
When using an abbreviation for the first time on an individual documentation page, start with the full form of an abbreviated word followed by the abbreviation in parentheses (). For example, "source (src)".
The following abbreviations are acceptable in their shortened form:
Also, avoid Latin abbreviations such as: "i.e." or "e.g.", etc. Instead, spell them out, "that is" or "for example".
Use external product names in the same way as they are used industry-wide. For example, CocoaPods, iOS, Android, React Native, npm, Yarn, macOS, GitHub, Node.js, ESLint, JavaScript, TypeScript, etc.
Always use a capital "B" for bytes. Write "bit" or a lowercase "b" for bits. For example:
For an in-detail reference on Bytes and Bits, read the Writing API documentation.
In most cases, to refer to multiple platforms (Android, iOS, and Web) in one sentence or to order sections on a particular page, follow the pattern: "Android, iOS, and Web".
When referencing Expo Go, the supported text should avoid implying: "running an app", "developing an app", or "previewing an app". One alternative to avoid these constraints is: "testing your project".
When referencing the multiple variants of app config file, such as app.json, app.config.json, app.config.js, or app.config.ts, use "app config" or "app config file" and link to its documentation page. This helps the reader understand that these files are interchangeable and can be used in the same context.
If there is a need to reference a specific file format, use the appropriate file name.
Generally, use Oxford commas. The need for an exception is often because it proliferates the population of commas in a copy block. Try instead to avoid this problem altogether (maybe one "," can become a "—" or a ":", or you need a simpler sentence) rather than omitting the Oxford comma.
One exception to avoid them is in headings for sections or sub-sections.
The possessive of singular nouns is formed by adding an apostrophe 's. This is true no matter the final consonant. The possessive of plural nouns that end in s is formed by adding just the apostrophe at the end.
Exceptions to this guideline are the following:
Do not add extra space between preceding and succeeding words and "/" just to emphasize them.
Try splitting phrases into separate sentences. Our goal is to make documentation easier to read and understand.
In rare cases when it is necessary to split phrases, use em dashes (—) or use connections (such as then, however, and so on) rather than commas to split phrases that read as separate sentences.
Guidelines for formatting in different situations, such as file names, inline code blocks, and so on.
On a page, top-level headers should use H2 in the markdown files. Also, do not skip heading levels just to emphasize a sub-section.
Use sentence case for section or sub-section headings inside an individual page except when the header uses an Expo tool, a service, or an external product name. Developers are familiar with Expo or external product names. Following these ubiquitous naming conventions makes the documentation more readable and scannable.
If the section or the sub-section heading refers to a product name such as Expo, Expo CLI, Expo Application Service, and so on, then capitalize them.
We, sometimes, have buttons that lead to an Expo Snack. Use title case for these or any type of text on buttons. While following the title case, we have a rule of thumb to not to capitalize articles, prepositions, and conjunctions.
File names, directory names and file extensions are used as bold text in the markdown files.
Example:
app.json/app.config.js.Example:
android or ios directories, it won't work.Example:
Do not use capitalized words to emphasize them.
Exception: Always capitalize product phrases:
Link the appropriate text rather than using the word "here". The linked text should describe the destination page and act as a Call to Action (CTA):
Use internal links when referencing a documentation page/topic that already exists. This helps avoid referencing the same piece of information copied from multiple places and gives the subject a single source of truth. For example:
When linking to the Expo FYI pages, use shorthand links, such as https://expo.fyi/bundle-identifier instead of the full URL (https://github.com/expo/fyi/blob/main/bundle-identifier.md).
An accessible document is created to be as easily readable by a sighted reader as a low vision or non-sighted reader. One of the key points to keep in mind when writing documentation and using images and videos is to add an "alt" text to them.
When referring to images or videos in Markdown (.md files), use the "alt" text. You can add the alt text in square brackets "[]" when adding an image or a video. For example:
Only apply inline code formatting using back-ticks (``) on programming words and commands:
async before the function keyword to set up an asynchronous function.File menu, then click Save As to export the file as a specific file type.—In some scenarios, when you split two sentences and use - or --, instead use —. Markdown renders that em dash nicely instead of a hyphen (-).
Keyboard shortcuts mentioned in the text should use the <kbd> element in markdown files. Each key should be wrapped with a separate tag, and plus signs should remain outside the elements:
⌘+t or ctrl+t to open a new window.A few points to remember:
Do not use emojis in the documentation.
To avoid inconsistency when referencing to install global packages with a package manager like npm or Yarn, use npm.
When a collapsible component has a single item or a paragraph to represent text, do not use a list item (or a bullet point) to emphasize it. It is unnecessary.
Avoid mentioning or using the terms to represent outdated/archived workflows, such as managed or bare workflow.
To avoid using the term "managed workflow", use "using Expo" to represent the current state of the Expo ecosystem. This is now the default way of explaining things.
When offering guidance for projects that require manually editing native code/directories, put those instructions in a dropdown saying "manual setup", or "usage in bare React Native projects", or "usage in existing React Native projects".
Any numbered list should start with 1 instead of 0. This avoids inconsistency across all areas in the documentation.
In Expo and Expo SDK documentation, use later and/or earlier to describe a range of version numbers.
Using a visual or an interactive example approach to communicate the correct information to our reader is another guideline we follow throughout the documentation. Consider using one of the following tools when necessary:
Terms referred in this section are meant to be used consistently throughout the documentation:
A complete list of Expo related glossary terms is available for further reference.
Writing API documentation accurately and precisely helps developers use our APIs correctly. In the following sections, we discuss the guidelines for properly documenting comments and some formatting tips to take care of when writing API docs.
| Tag | Usage |
|---|---|
@return / @returns | Describes the return value. |
@param | Adds a description to method arguments. Syntax: @param [param_name] [description]. |
@default | Does not support Markdown formatting. All content is placed directly in the InlineCode block, so there is no need to wrap the value with ``` manually. |
@platform | Available platforms: android, ios, web, expo (Expo Go). |
You can specify a minimum version or range, for example, @platform ios 11+. | |
Currently, specifying multiple platforms (or lists) per one tag is not possible. Use multiple @platform tags to list more than one platform. | |
@example | Adds the "Example" header and puts content at the bottom of the description block. |
@see | Wraps the message in a note/quote block and adds "See:" at the beginning of the message. |
| The See section is placed after the main comment content. | |
@deprecated | Wraps the message in a note/quote block and adds "Deprecated" at the beginning of the message automatically. A message is optional. |
| The deprecation note is always placed at the top of the generated doc comment, no matter where you put it in the doc block content. | |
@experimental | Adds an "Experimental" label to the property when used. |
@internal / @private / @hidden | Any of those annotations will hide the code and comments from the autogenerated API docs output. |
@hideType | Hides the generated Type callout for constants in the API docs when the type should not be displayed. |
@header | Allows grouping methods by custom headers, used with the headersMapping prop for the APISection component to control header titles and their order (see expo-notifications source and doc page for an example usage). |
./ instead of ../ at the beginning of the URL
21^st^ Century <!-- sup -->
H~2~O <!-- sub -->
Warning: The
@linkinline tag is not supported in docs. Use standard Markdown links instead for internal and external links.
These are some topics that often come up with Expo development:
Concurrency describes two tasks logically running together. Two concurrent tasks may each start before the other finishes. Parallelism describes two tasks physically running at the same time. Two network requests or processes running on two CPU cores are examples of parallelism.
It is possible, and very common with JavaScript, to have concurrency without parallelism. Two async functions without external I/O will run concurrently but not in parallel because the JavaScript micro task scheduler will interleave the async functions but run them single-threadedly.
new Promise(resolve => resolve(anotherPromise))await Promise is never a promise.The returned promise is fulfilled with a
CameraPhotoobject.
await capturePhotoAsync().The returned promise resolves to a
CameraPhotoobject.
capturePhotoAsync() is resolved.The returned promise is resolved with the given promise if it settles before the specified timeout.
resolve function with another promise. This settles the first promise with the result of the second.Unless you have a specific reason to use "URI", use "URL" everywhere. This follows the WHATWG URL specification's goals.
Standardize on the term URL. URI and IRI are just confusing. In practice, a single algorithm is used for both, so keeping them distinct is not helping anyone. URL also easily wins the search result popularity contest.
Use /** ... */ for multiline docblocks that describe functions, methods, classes, and other types. Format them to fit the column width of the file at hand, which is 100 columns for most of our files. The Rewrap (stkb.rewrap) VS Code extension makes it easy to reflow most docblocks.
Write descriptions using the third-person declarative instead of the second-person imperative.
Explain the behavior of functions beyond their parameters and return values. Those are easy to see, but it's less clear what the failure modes, side effects, expected preconditions, and concurrency safety are. Document the parts of the iceberg below the surface.
Write useful descriptions of parameters and fields. Teach the developer something useful. If you don't have anything useful to say, leave out the documentation and put quality over quantity.
type CameraResult = {
// CORRECT:
/**
* The width of the captured photo, measured in pixels
*/
width: number;
// INCORRECT:
/**
* The width
*/
width: number;
// ACCEPTABLE BUT WE CAN DO BETTER:
width: number;
...
};
Leave off a period if the description of a function, parameter, return value, etc... is just one phrase. Use a period when writing subsequent sentences.
Example:
/**
* Captures a still photo with the camera's current settings and given configuration options. The
* image will be encoded using the specified format. If the format is not supported by the device,
* this method throws an error.
*
* Upon capturing the photo, it is written to the device's temporary file storage. The file will be
* accessible right after this method completes but may be cleared by the device OS at an arbitrary
* time afterward; do not assume the file is permanent.
*
* @param options configuration options that specify the file format, image quality, and more
* @returns a promise fulfilled with information about the captured photo, including its location on
* disk
*/
expo/docs repository locally and what the requirements are for contributing to the expo/docs/README.md file.