When contributing to the docs, follow the rules in this style guide.
The Segment docs team uses Vale as a linter, or tool that helps you follow the style rules in our style guide. To run Vale:
- Navigate to the
segment-docsfolder, and open it in your terminal. - In your terminal, copy the relative link to the .md file you'd like to run through Vale.
- Type 'vale [relative-link]' into your terminal and press enter.
VSCode users can also download and install the Vale extension{:target="_blank”} to run Vale on demand.
| Rule | Description |
|---|---|
| Title casing for article titles | Use title case for article titles and the nav. For example, instead of Data export options → use Data Export Options. |
| Sentence casing for headings | Article headings should be in sentence case, meaning you only capitalize the first word and any product names and proper nouns. For example: |
| Rule | Description |
|---|---|
| Active voice | Write in active voice whenever possible. Instead of referring to something that will happen (Segment will create), rephrase it in the present tense (Segment creates). Other examples: You'll see a new dialog → A dialog appears |
| Third-person | When referring to ourselves as a company, use Segment. Avoid the following: When referring to a third-party, use a name. Avoid the following: |
| Rule | Description |
|---|---|
| No latin abbreviations | e.g. → use for example i.e. → use that is, for example. |
| Don't use that → use this | blacklist → use blocklist whitelist → use allowlist utilize(s) → use use(s) leverage(s) → use use(s) via → use through, using drop in → use enter & → use and login → use credentials, account setup → use configuration |
Correct use of might, may, can |
might when something could possibly happen. For example, “Depending on your configuration, you might see different options.” may to grant a user permission to do something. For example, "You may add optional notes in this section." can to apply the ability to do something. For example, "You can use Personas to send data to your marketing tools." |
| Weasel Words | Avoid words that don't add substance to a sentence. For example: you can run virtually any type of application... The word virtually does not contribute to the meaning of the sentence. If you're going to add an adverb or adjective to a sentence, make sure it contributes to something. |
| Contractions | Use contractions. For example, can't, won't, haven't |
Using click or select |
Use click when a user should take action on a single item. Use select when the user should pick an item from a list. |
The use of At this time, Currently |
Generally, don't use such words/phrases, except when the feature is half rolled out or in beta. |
| Projecting ease of something | Avoid trying to convey the ease with which something can be accomplished. For example: You can easily... With this simple... It's not up to us to determine how difficult or easy someone will find a task. |
| Rule | Description |
|---|---|
| Field names in any app | Bold the use of field names. |
| Hyperlinks | Link to the noun or topic of the article rather than here. |
| Numbers | Use digits/numerals in all cases, except at the beginning of a sentence. For example, instead of There are five options to choose from. → use There are 5 options to choose from. |
| Entered text in the app | Use code format |
| Capitalization | Capitalize Segment and Segment product names. For example, "privacy" by itself isn't capitalized, but "Segment Privacy Portal" is. Page titles and other UI text should be in lower case. Capitalize the words "Sources", "Destinations", and "Warehouses" when referring them as product names (for example: “You can use Sources to…”) but decap them when referring to them generically (“You can connect your warehouse to…”) |
we and they |
Avoid using we and they. Be explicit about naming who is being referenced. Because Segment has such a large footprint of documentation around third-party integrations, it's important to be very clear about who "we" are in any given part of the doc. Instead of using "we", your should refer to our software or processes in the third person: "Segment creates..." "Segment sends..." |
| Sub-bullets/sub-lists | If there are mutliple tasks within a step, break it up into a sub-list. A single task should be no longer than 3 sentences. |
| FAQs | Use H4s for FAQs. Don't use the liquid formatting. When naming the FAQ section, use FAQ instead of Frequently Asked Questions. |
| External links | When inserting links that aren't on the segment.com/docs subdomain, follow this format: [link text](https://google.com){:target="_blank"} Make sure the {:target="_blank"} is included after the link. This ensures that the link to the external site opens up in a new tab to avoid taking users away from the docs site. |
| Code blocks | When giving a code example that is more than a line long, use a code block. (For keyboard shortcuts, variables, and commands, use the single-backtick code format). Always use triple-backtick code fences to create a code block. Do not use the three-indent (three tabs/six spaces) mode, as this can conflict with nested list rendering. |
| HTTP response codes | When including an HTTP error code, write the entire code (for example, 400 Bad Request) and format the error code using single-backtick code format. |
| Rule | Description |
|---|---|
| Libraries vs SDKs | Segment Source libraries are libraries, not SDKs. The bundled destination dependencies are SDKs. Technically, an SDK often contains a hardware component, or is closely tied to a unique developer key or development-only hardware device - for example, an PlayStation SDK includes a software license key and test hardware linked to that account, an Apple SDK includes a developer key. A library is any modularlized piece of code that can be added to or invoked by a larger project. |
| Styling Segment Methods | When you refer to a method outside of code, use: Avoid styling like inline code: page() .identify() Identify call |
| Styling Segment Events | When you refer to an event outside of code, format it like inline code. For example: Product Viewed or Clicked Login Button. |
| Connection modes | Device-mode and Cloud-mode are always hyphenated. They should be capitalized when referring to the mode in abstract (as a product name), but can be decapped when used in running text about a specific destination. We’ve had a lot of confusion in the past due to using device-mode and client-side, and cloud-mode and server-side interchangeably when referring to our Connection Modes. There are legitimate uses of both the terms client-side and server-side when referring to things other than our connection modes, so we’re moving to use Device-mode and Cloud-mode instead. |
| Sources and destinations | When you refer broadly to sources or destinations, don't capitalize source/destination. For example, "A source is a website, server library, mobile SDK, or cloud application..." If you're referring to the full name of a source or destination, like Slack (Actions) Destination or Facebook Ads Source, for example, capitalize source/destination. |
| Rule | Description |
|---|---|
| Screenshots | Use screenshots sparingly. Screenshots are hard to maintain and don't add much value. Confirm that they are essential to understand the feature you're documenting. PR reviewers should monitor for screenshots and help determine if they are necessary. Save all images locally and don't link them to 3rd party-hosted images. To add images to a docs page, create an images folder for the docs path, save the image to the folder and then reference it in your markdown file. The Google Analytics destination is a good example. |
| Alt text | Provide brief alt text that can be helpful for accessibility. Follow this format for including images with alt text:  |
We have some fairly complex CSS, and lists with lots of "stuff" in them. Normally, the way you make Markdown include something as part of a list item is to indent it the same number of places as the number. Unfortunately Markdown also maintains backwards compatibility with an archaic method of invoking a code block, which is to indent it four spaces or two tabs. You can probably guess how this works out...
On top of this, some of the Premonition callouts we use, for some reason, break list ordering. So you can't add an "info" box inside a running list. (Boooo.)
To get around this, you can let the previous list item end wherever if needs to, then create an entire new ordered list with specific HTML to allow you to override the start number.
<ol style="counter-reset: none;">
<li value="5" markdown=1>
<!--list item contents here-->
</li>
<li value="6" markdown=1>
<!--list item contents here-->
</li>
</ol>Do this with great caution, and only when absolutely necessary. Because you're explicitly setting the numbers, they won't update if you add or delete a step in the auto-numbered list above.
Tables can be a mix of markdown and HTML, but they can't be both markdown and HTML on the same line.
Tables in HTML can include html formatting, OR markdown formatting, but not both in the same cell. We built a ruby hook that adds a markdown=1 cue to all <td> elements at build time, which allows Kramdown to interpret and render their content normally. This doesn't apply to <th> tags, and it also means that you can have (for example) <p> paragraph markers inside a table cell.