Style guide

This style guide explains our guidelines for contributions to Telepath's documentation, tutorials, and blog.

General principles

Assume almost nothing

As you master a product or feature, some things become second nature, but remember they weren't always so obvious. Call these out and provide links to relevant documents or websites.

Make it easy for your readers to implement your feature or solve their issue, whether they are experts or just starting with Telepath.

Avoid hedging

We are opinionated at Telepath. That means avoiding hedging like saying "It's complicated" or "It depends." This is frustrating for the reader and doesn't add value. Instead:

1. Have an opinion.

2. Provide an example.

3. Research until you can do 1. or 2.

Avoid overly long intros

Most articles can be improved by making the intro shorter and more direct. Two brief paragraphs, or less, is preferable, though there will always be exceptions.

Brand guidelines

We're an analytics platform, not a product analytics tool

Unless directly referring to our product analytics suite, substitute references to "product analytics" or "product analytics tool" with the phrase "analytics platform".

Example: “A product analytics tool like Telepath can be helpful here.” would become “A analytics platform like Telepath can be helpful here.

Product OS is also an acceptable alternative – use your judgment based on the context.

Do not capitalize product features

It's "product analytics" not "Product Analytics" and so on.

Style rules

Use American English

Telepath is a global company. Our team and our customers are distributed around the world. For consistency, we use American English spelling and grammar.

Use the Oxford comma

Write "bananas, apples, and oranges", not "bananas, apples and oranges".

Use "enable", not "allow"

Allow is another way of saying permit.

Example: Your partner allows you to stay up late and play video games.

Enable means providing the means or opportunity.

Example: Telepath enables you to understand user behavior.

In most cases, Telepath enables users to do things.

Use straight apostrophes and quote marks

Many writing tools, such as Google Docs, Notion, and Word, add curly quotes and apostrophes. Please avoid using these. They can normally be turned off in the settings.

Capitalize proper names as appropriate

Write "Redis server", not "redis server".

Capitalize acronyms and define where needed

Write "URLs", not "urls".

Many acronyms, like that one, will be familiar to developers. When in doubt, link the first use of an acronym to a definition, or provide one.

Use sentence case for titles

Write "Documentation style guide", not "Documentation Style Guide".

Use snake case for Telepath events and properties.

Use snake_case, not camelCase or PascalCase for Telepath events and property names. For example:

JavaScript

telepath.capture('user_signed_up', {  user_id: '123',  username: 'Jane Doe',})

Always provide a link

Don't just write "You can contact us to learn more" and not link it to anything.

Write "To learn more, log a ticket with details of your request."