Skip to content

Commit 70ac1df

Browse files
stayseesongstayseesong
authored
Merge pull request #5757 from segmentio/style-guide-update
Style guide update
2 parents a3cea63 + d32aeaf commit 70ac1df

File tree

1 file changed

+57
-180
lines changed

1 file changed

+57
-180
lines changed

‎styleguide.md

Lines changed: 57 additions & 180 deletions
Original file line numberDiff line numberDiff line change
@@ -1,135 +1,60 @@
11
# Style guide
2-
3-
This doc is for keeping track of [style decisions](#style-decisions), [structure decisions](#doc-structure), and [formatting gotchas](#formatting) in the Segment Docs.
4-
5-
## Style decisions
6-
7-
## General text style
8-
9-
- Titles and headings should be in sentence case, meaning you only capitalize the first word, and any product names and proper nouns.
10-
11-
- UI items are described by their text label in **Bold**. We don't add an explicit reference to what type of affordance it is (button, toggle, etc) unless needed for clarity. "Click **Send**." rather than "Click the **Send** button."
12-
13-
- Use single-backtick `code format` for variables, for commands or values that need to be entered by the user, and the names of methods or calls when referring to them in context of an implementation (for example: "You'll make an identify call to capture this information" vs "In your code, edit the `identify` call...").
14-
15-
- One-line or less of code can be formatted using single-backtick "code format". For more than one line of code, use a code block.
16-
17-
- Code blocks must use the triple-backtick format, and must include a syntax highlighter cue (even if that cue is "text" or "none".)
18-
19-
### Use Active Voice / Write in the Present / Yes We Do
20-
21-
Write in the active voice.
22-
This one is harder to encapsulate.
23-
24-
Instead of saying "Segment will create..." use "Segment creates..."
25-
Instead of saying "You should see your data in (x) minutes..." use "Your data arrives within..."
26-
Instead of saying "You will see a new dialog with your key..." use "A diaglog appears and displays your key..."
27-
28-
### We and they
29-
30-
TL:DR: Avoid the words "we" and "they". Be explicit about naming who is being referenced.
31-
32-
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..."
33-
34-
This is especially important with destination partners. Instead of writing "we create a new table schema and they ingest it" write "Engage creates a new table schema, and FancyIntegration ingests it."
35-
36-
### Might, may, can
37-
38-
These three often have overlapping understandings of meaning, but in technical docs it's good to be *very* clear about which one to use.
39-
40-
- **Might** means a thing could possibly happen. Use this for example, when you're describing an unknown environment: "You might see additional options depending on your pricing plan." Or when describing something where we don't necessarily know what is needed or what will happen: "Depending on your configuration, you might..." or "You might want to ..."
41-
42-
- **May** grants permission to the user to do something. "You may omit this value."
43-
44-
- **Can** implies ability to do something. "You can use..." Or "If your implementation needs it, you can..."
45-
46-
### Styling the Segment Methods
47-
48-
We've traditionally been pretty scattered about how we describe the Segment Methods in our running text. In general: capitalize it when referring to the method in general ("You use a Page call to..."), but capitalization is optional when referring to a specific call in an implementation or code snippet ("The page call on line 38...")
49-
50-
Omit the empty parentheses. :)
51-
52-
This styling guidance applies to any prose mention of the methods that is *not* styled as code, including fenced code blocks, and longer phrases contained in code-format backtics.
53-
54-
✅
55-
- Page call, Page method
56-
- Identify call, Identify method
57-
- ...etc
58-
59-
👎
60-
- Page() method
61-
- `page()`
62-
- `.identify()`
63-
- `Identify` call
64-
65-
### Libraries vs SDKs
66-
67-
We want to help readers distinguish between Segment's software, and the device-mode destination-specific pieces they may need to bundle. Using language very specifically here will help readers distinguish between them.
68-
69-
For our purposes:
70-
- The Segment Source libraries are libraries, _not_ SDKs.
71-
- The bundled destination dependencies are SDKs.
72-
73-
NB, LR 11/12/2020: 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.
74-
75-
76-
### When to capitalize
77-
78-
Capitalize Segment (obviously ;) ) 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.
79-
80-
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…”)
81-
82-
Other items that can be capitalized:
83-
- Segment Methods (when referring to the Spec methods collectively)
84-
- Page, Screen, Track, Identify, Group, Alias calls, when referring to them as a class of calls.
85-
86-
Don't capitalize these:
87-
- partners
88-
- write key
89-
90-
### Connection modes
91-
Device-mode, Client Side, Cloud-mode, Server side
92-
93-
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. To reduce confusion, we’re standardizing.
94-
95-
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. Laura made an initial scrub through to change all instances of “client-side” to “device mode”, but there are some legitimate uses of “server side” in the docs which prevent us doing a full find-and-replace to change those.
96-
97-
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.
98-
99-
### Use this not that
100-
101-
- Don't use characters like ampersand (`&`) or plus (`+`) -> Use the word "and".
102-
- Don't use "ie" or "eg", write out "for example".
103-
- Don't use the word "via". Instead use the words "using", "with", or sometimes "through" as appropriate.
104-
- Setup is one word describing a noun ("your recording studio setup") which we should more properly call "configuration." "Set up" is an action, and requires a space.
105-
- "Login" is a noun, and we should use "credentials", "account", or similar instead. "Log in" is an action, and requires a space.
106-
- Replace big words like leverage, utilize, utilizing -> Use "use"
107-
108-
## Doc structure
109-
110-
### Adding Images
111-
112-
**All images should be saved locally! No linking to 3rd party-hosted images!**
113-
As CDN hosting is from the publish side, we shouldn't be worrying about that at the file level.
114-
115-
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](/src/connections/destinations/catalog/google-analytics) is a good example.
116-
117-
There are no naming conventions at this time. Anything you see with `asset` was dowloaded by a script to save it from Contents.io. :)
118-
119-
### Signposting
120-
121-
The Segment-App section should contain roughly a page for each page within the web app. If there are in-depth docs about that feature elsewhere, the page should describe what it does at a high-level, and link out to those docs. This gives us a comprehensive UI reference for novice readers that serves as a signpost to the details they may or may not need, and prevents us pulling all of the docs into the Segment-app section.
122-
123-
### External Links
124-
125-
It is convenient to open any link to an external site in a new tab or window to avoid taking users away from the docs site. The Kramdown markdown parser supports with with the following syntax:
126-
127-
```
128-
[link text](https://google.com){:target="blank"}
129-
```
130-
131-
The site's CSS adds an external link indicator next to the link text when the page is rendered.
132-
2+
When contributing to the docs, please try to follow the rules in this style guide.
3+
4+
## Format for titles and headings
5+
Rule | Description |
6+
---- | ------- |
7+
Title casing for article titles | Use title case for article titles and the nav. <br><br> For example, instead of `Data export options` &rarr; use `Data Export Options`.
8+
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: <li> Query the User's Event Traits &rarr; Query the user's event traits
9+
10+
## Voice and point of view
11+
Rule | Description |
12+
---- | ------- |
13+
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`). <br><br>Other examples: <li> `You'll see a new dialog` &rarr; `A dialog appears`
14+
Third-person | When referring to ourselves as a company, use *Segment*. Avoid the following: <li> we, we've, we're <br><li>our, ours <br><li>us <br><li>let's <br><br>When referring to a third-party, use a name. Avoid the following: <li> their
15+
16+
17+
## Wording rules
18+
Rule | Description |
19+
---- | ------- |
20+
No latin abbreviations | <li> Instead of `e.g.` &rarr; use `for example` <br><li> Instead of `i.e.` &rarr; use `that is`, `for example`.
21+
Don't use that &rarr; use this | <li> Instead of `blacklist` &rarr; use `blocklist` <br><li>Instead of `whitelist` &rarr; use `allowlist` <br><li>Instead of `utilize(s)` &rarr; use `use(s)` <br><li> Instead of `leverage(s)` &rarr; use `use(s)` <br><li>Instead of `via` &rarr; use `through`, `using` <br><li>Instead of `drop in` &rarr; use `enter` <br><li>Instead of `&` &rarr; use `and` <br><li>Instead of `login` &rarr; use `credentials`, `account` <br><li>Instead of `setup` &rarr; use `configuration`
22+
Correct use of `might`, `may`, `can` | <li>Use `might` when something could possibly happen. For example, “Depending on your configuration, you **might** see different options.” <br><li>Use `may` to grant a user *permission* to do something. For example, "You **may** add optional notes in this section." <br><li>Use `can` to apply the ability to do something. For example, "You **can** use Personas to send data to your marketing tools."
23+
Weasel Words | Avoid words that don't add substance to a sentence. <br><br> For example: `you can run virtually any type of application...` <br><br> The word **virtually** does not contribute to the meaning of the sentence. <br><br> If you're going to add an adverb or adjective to a sentence, make sure it contributes to something.
24+
Contractions | Use contractions. For example, `can't`, `won't`, `haven't`
25+
Using `click` or `select` | Use **click** when a user should take action on a single item. <br><br>Use **select** when the user should pick an item from a list.
26+
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.
27+
Projecting ease of something | Avoid trying to convey the ease with which something can be accomplished. For example: <li> `You can easily...` <br><li> `With this simple...` <br><br>It's not up to us to determine how difficult or easy someone will find a task.
28+
29+
30+
## Formatting
31+
Rule | Description |
32+
---- | ----------- |
33+
Field names in any app | **Bold** the use of field names.
34+
Hyperlinks | Link to the noun or topic of the article rather than `here`.
35+
Numbers | Use digits/numerals in all cases, except at the beginning of a sentnce. <br><br> For example, instead of `There are five options to choose from.` &rarr; use `There are 5 options to choose from.`
36+
Entered text in the app | Use `code format`
37+
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. <br><br>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…”)
38+
`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..."
39+
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.
40+
FAQs | Use H4s for FAQs. Don't use the liquid formatting. <b><br>When naming the FAQ section, use `FAQ` instead of `Frequently Asked Questions`.
41+
External links | When inserting links that aren't on the segment.com/docs subdomain, follow this format: `[link text](https://google.com){:target="blank"}` <br>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.
42+
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.
43+
44+
45+
## Segment Specific Terms
46+
Rule | Description |
47+
---- | ----------- |
48+
Libraries vs SDKs | Segment Source libraries are libraries, not SDKs. The bundled destination dependencies are SDKs. <br><br>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.
49+
Styling Segment Methods | When you refer to a method *outside* of code, use: <li>Page call, Identify call <br><br>Avoid styling like inline code: <li> Page() method <br><li> `page()` <br><li> `.identify()` <br><li> `Identify` call
50+
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. <br><br>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.
51+
52+
53+
## Images
54+
Rule | Description |
55+
---- | ----------- |
56+
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. <br><br>PR reviewers should monitor for screenshots and help determine if they are necessary. <br><br> 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](/src/connections/destinations/catalog/google-analytics) is a good example.
57+
Alt text | Provide brief alt text that can be helpful for accessibility. Follow this format for including images with alt text: `![description of image goes here](resource path of image file goes here)`
13358

13459
## Troubleshooting Formatting
13560

@@ -155,61 +80,13 @@ To get around this, you can let the previous list item end whereever if needs to
15580

15681
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.
15782

158-
### Mixed markdown and HTML
159-
160-
You can mix markdown and html in the same file, but you need to be careful to keep these items on separate lines. The one exception to this is
161-
162-
### Code fences and syntax highlighter cues
163-
164-
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`)
165-
166-
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.
167-
168-
When you create a code fence, add a syntax highlighter cue after the first set of backticks - this tells the renderer how to color the text for better readability. We use Rouge, and you can read the [long list of the cues Rouge accepts](https://github.com/rouge-ruby/rouge/wiki/list-of-supported-languages-and-lexers) to find one that works for your code snippet.
16983

17084
### Tables
17185

172-
Tables can be a mix of markdown and HTML, but only they can't be both markdown and HTML on the same line.
173-
174-
Markdown tables are built on a single line per table row, and so have to be pretty much 100% markdown. Markdown tables aren't fun, but you can install the Atom `markdown-table-editor` package which makes them easier to work with.
86+
Tables can be a mix of markdown and HTML, but they can't be both markdown and HTML on the same line.
17587

17688
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.
17789

178-
## Troubleshooting Paper Exports
179-
180-
Many of these docs were exported from Paper, which means that they'll have some quirks to sort out.
181-
182-
### Endumben-ing
183-
Paper uses smart-quotes and smart apostrophes, which often can break syntax-sensitive formatting. You can replace them with "dumb" or straight quotes. The characters you're going to want to look for are...
184-
185-
’ ‘ “ ” If you "change all" in Atom, you'll remove these examples so please revert changes to this file. ;)
186-
187-
Note that these won't always render in Github, so you'll have to make this change using Atom or another text editor.
188-
189-
If the examples get removed you can also type these on a Mac by typing
190-
- Option + [
191-
- Option + Shift + [
192-
- Option + ]
193-
- Option + Shift + ]
194-
195-
### Headings vs Titles
196-
197-
Our titles are our H1s, so you can remove a top-line H1 if if shows up, and demote all following ones. (This assumes you're using heading formats semantically and not just for formatting. :P )
198-
199-
### Image captions
200-
201-
What Paper uses as the "caption" is actually what's specified as the "alt text", meaning what a screen-reader would vocalize. It ends up inside the "image" declaration tags.
202-
203-
```md
204-
![alt text goes here](resource path goes here)
205-
```
206-
207-
If you want to preserve this as alt-text, awesome. However, if you want to use this as a "caption", you'll have to copy and paste that text below the image. You can put it in italic format if you'd like.
208-
209-
### Code-block cleanup
21090

211-
By default, Paper uses an old style of markdown that allows you to start a code block by indenting the block. This is rendered okay on our end, but can screw up your code's indentation.
21291

213-
Instead, de-indent your code (shift-tab), and add a code-fence of three backticks at the top and bottom.
21492

215-
If you know what language it's in, you can also add a "cue" to the first codeblock, which improves how the syntax highlighter renders it (assuming it knows how to format that specific language). See the [section on code fences](#code-fences-and-syntax-highligher-cues) above for more details.

0 commit comments

Comments
 (0)