Skip to main content

​
TL;DR

Use the fewest words and the simplest language possible to get your point across. Be friendly and informal but get straight to the point. Maintain the present tense and frame actions in terms of “you” the user (rather than “we” the company). Avoid adding too much Markdown style stuff to your text (and see the section below on UI elements and interaction if you’re unsure how to apply styles to text that describes user interfaces). The sections that follow explain these preferences in more detail and list the specific style rules that we adhere to in the documentation. If you ever have any questions about style you can reach out to the docs team for more info.
Did Vale send you here because of a style issue in your docs PR? See the Vale rules section for more information about how to resolve it.

​
LLM skill files

The .skills directory contains skill files for various documentation tasks. When writing or editing docs, you can provide these files as context to the LLM of your choice to help standardize the style and ensure your work conforms to the style guide.

​
Voice, tone, and style

​
Basics

The docs should feel approachable and conversational. The information should be technically accurate and precise, but the presentation should feel natural rather than academic. Try to sound like a knowledgeable friend who understands what the reader wants to accomplish. We’re writing for an international user base, many of whom may not have strong English language skills. We always prioritize the simplest and clearest way of expressing ourselves in the interest of being understood by everyone. Target 8th-grade-level English. (Our industry and niche often require us to use complex terminology, but we should always be mindful to explain that terminology with this benchmark in mind.)

​
Maintain present tense

Favor “A does B” instead of “A will do B.”
As a general rule, always maintain present tense throughout documentation. When you slip into future tense in procedural guides, or when describing the order in which events take place with the software, you risk the reader losing track of what’s supposed to happen and when.
  • ✅ Navigate to Endpoints and click Add New. On the screen that follows, choose your binding and protocol then click Confirm.
  • ❌ Navigate to Endpoints and click Add New. Then there will be another screen where you’ll be able to choose your binding and protocol.
    • [When? Immediately, or at some later time?]

​
Write to “you” the reader

Favor “You do X” instead of “We’re going to do X.”
Always frame documentation in terms of “you” the reader and what actions “you” need to take. Avoid mentions of “we” or “us” as in the company / docs writers. The reader doesn’t care about us—they have problems and they want to know how our product solves them. Similarly, avoid “let’s” as in “let’s start by installing the Agent CLI”—“we” the writers are not involved in the process that the reader is going through.
  • ✅ This guide shows you how to configure ngrok to run with X and Y third-party platforms.
  • ❌ In this guide we’ll look at how to configure ngrok…
    • [“we” are not involved in what the reader is doing.]

​
Use active voice

Favor “X does Y” instead of “Y can be done by X.”
In general, active voice is preferred over passive because it’s more concise, direct, and reader-focused. In the active voice, the subject performs the action; in the passive voice, the action’s target is positioned first as the focus of the sentence. There are occasionally valid reasons for this construction—such as when you need to emphasize the action over the subject—but always consider whether it’s really necessary.
  • ✅ You can configure your endpoint settings in the dashboard.
  • ❌ Endpoint settings can be configured in the dashboard.
    • [By whom?]
  • ✅ Exception: Your message was flagged by our Support team.
    • [The action—the user’s message being flagged—is more important than the subject, our Support team.]

​
Use the imperative mood

Favor “To accomplish Z, do X and Y” instead of “If you want to accomplish Z, you should do X and Y.”
The imperative mood describes commands and actions. Much of our documentation is procedural, meaning it consists of a series of actions the user must take to accomplish their goal. Writing in the imperative mood is the simplest and most straightforward way to describe procedural steps.
  • ✅ Go to Settings > Advanced and click Configure.
  • ❌ You should go to Settings > Advanced and there will be an option there called Configure. [I “should” or I “must”? Are you actually instructing me to click on Configure or not?]

​
Best practices

​
Maintain one sentence per line

When writing in Markdown for our docs, please maintain one sentence per line in your IDE. In other words: add a single line break after each sentence, regardless of length. (It takes two line breaks to create a new paragraph, so this has no impact on the final rendered text.) Why? This makes it much easier to do line-by-line reviews on GitHub. It also prevents contributors from adding arbitrary line-wrapping breaks in the middle of sentences, which (along with complicating the review process) can lead to a poor experience for others who may be using different window sizes or screen resolutions. (If you’re inclined to add line-wrapping breaks to your Markdown, please configure your IDE to automatically wrap text for you instead.) Consider reviewing a paragraph like this on GH:
1 A Domain’s primary responsibility is to enable you to create public endpoints with a hostname matching the domain. These are called “matching endpoints”. For example, after you create the Domain app.example.com, you can create the Endpoint https://app.example.com.
  • ❌ This can be annoying to add suggestions to—I really want to put that period inside of the quotes in that second sentence, but because it’s all on one line, I have to leave a suggestion for the entire paragraph just to propose this tiny fix. And if I need to make multiple suggestions elsewhere in the paragraph, it becomes difficult to track what’s changed in the GH UI.
Compare with this style:
1 A Domain’s primary responsibility is to enable you to create public endpoints with a hostname matching the domain. 2 These are called “matching endpoints”. 3 For example, after you create the Domain app.example.com, you can create the Endpoint https://app.example.com.
  • ✅ Now I can suggest changing sentence 2 to These are called "matching endpoints." without having to touch the rest of the sentences in the paragraph.

​
Don’t create nested numbered lists

If your doc is a procedural guide with a set of steps outlined in the headers, avoid creating additional numbered lists within the steps—it becomes increasingly difficult for the reader to keep track of where they are as you subdivide the steps this way. If you find yourself doing this, consider:
  • are you being too granular with your steps (unnecessarily holding the user’s hand through every single interaction)?
  • are these sub-steps actually “primary” steps that need to be separated out?
  • should these sub-steps instead have sub-headers (h3 and beyond) to delineate them?
  • do they all really need to be ordered lists, or would an unordered list work just as well for some?
  • ❌ 2. Installation and setup
    1. Open a new terminal window
    2. Run this command
    3. Enter the following config details:
      1. project name: whatever you prefer
      2. domain: your reserved domain
      3. endpoint type: agent or cloud
    4. Press Enter to continue.
  • ✅ 2. Installation and setup In a new terminal window, run this command and enter the following config details:
    • project name: whatever you prefer
    • domain: your reserved domain
    • endpoint type: agent or cloud Then press Enter to continue.

​
Grammar and mechanics

​
Abbreviations and acronyms

If there’s a chance your reader won’t recognize an abbreviation or acronym, spell if out the first time you mention it on the page. Then use the short version for all other references. If the acronym is well known (like API or HTML), don’t spell it out.

​
Contractions

They’re great! Don’t be afraid to use them—they make your text more friendly and informal (in a good way).
  • ✅ “If you’re interested in using feature x…”
  • ❌ “If you are interested in using feature x…”

​
Listing steps

Sometimes you need to add steps to a doc to guide a user through a process. We don’t currently have a Steps component, so for now just add the number of the step to the heading.
  • ✅ ## 1. Do the first thing
  • ❌ ## **Step 1** - Do the first thing

​
Titles and headings

Use title case for titles (the h1 on the page):
  • ✅ title: Getting Started with Cloud Endpoints
  • ❌ title: Getting started with cloud endpoints

​
Screenshots

✋ Avoid screenshots. When screenshots go out of the date, they create a frustrating user experience. Though they can be necessary, as much as possible we should avoid them in the following cases:
  • 💻 Screenshots of UI for companies/services outside of ngrok
    • Example: Don’t rely heavily on screenshots of the AWS dashboard. If their UI changes, they will not update us, and our screenshots will be wrong.
  • :ngrok: Screenshots of our Dashboard UI
    • As a startup, we change our UI quickly and frequently. The dashboard team can’t be expected to let docs know every time they make a change, so the odds of screenshots going out of date are high.

​
UI elements and interaction

When you’re documenting tasks that involve the user interface, focus on the task, not how the user interacts with the UI element. If you do document elements of the UI, put UI element names in bold, and use appropriate nouns and verbs to describe how to interact with them. From Google developer documentation style guide—UI elements and interaction.

​
Focus on the task

State instructions in terms of what the user should accomplish, rather than focusing primarily on widgets, icons, and gestures. This helps the user to understand the purpose of an instruction and can help to future-proof documentation. Keep in mind that context is key: there may be instances where it’s necessary to guide the reader through the elements on the page.
  • ✅ Refresh the page.
  • ❌ Click the Refresh button in the upper left corner.
    • [The Refresh button might not always be located in the upper left corner, but it’s safe to assume that our readers know how to refresh a page.]

​
Formatting names of elements

When referring to any UI element by name, put its name in bold using ** in Markdown (preferred) or <b> in HTML.
  • ✅ In the New Project window, select New Table.
  • ❌ In the “new project” window, select New Table.

​
Buttons and icons

A button initiates an action when clicked. To refer to a button, use the button’s label.
  • ✅ Click Yes.
  • ❌ Click the “Yes” button.
Don’t use directional language (above, to the left, etc.) to orient the reader. These words won’t generally make sense when a screen reader is being used. If a UI element is hard to find, provide a screenshot.
  • ✅ Click Menu.
  • ❌ In the top right corner, click the icon with the horizontal lines to open the menu.

​
Vale rules

You can provide the Vale Style Rules skill file as context to an LLM to help you resolve Vale warnings and errors more efficiently.
The following sections document all Vale rules used in the ngrok documentation. Vale is a prose linter that helps maintain consistency and quality across documentation. You can run vale locally with pnpm run vale to check your changes for style issues. Vale also runs automatically as part of our CI pipeline when you submit a pull request, and it will leave comments on your PR with any style issues it finds.
Warnings versus errors:
  • ❌ Errors flag critical style issues that must be addressed before merging. There should be no exceptions or false positives.
  • ⚠️ Warnings flag style issues that are not critical but should be addressed for consistency. There may occasionally be exceptions or false positives.

​
Time format (AM/PM)

Use “AM” or “PM” preceded by a space. Do not use lowercase, periods, or omit the space.
  • ✅ 3:00 PM
  • ✅ 9:30 AM
  • ❌ 3:00PM
  • ❌ 9:30am
  • ❌ 3:00 P.M.
  • ❌ 9:30 a.m.

​
Capitalize ngrok-specific terms

Always capitalize these ngrok-specific terms:
  • ✅ Traffic Policy
  • ✅ Kubernetes Operator
  • ✅ Traffic Inspector
  • ✅ Cloud Endpoint
  • ✅ Agent Endpoint
  • ❌ traffic policy
  • ❌ kubernetes operator
  • ❌ traffic inspector
  • ❌ cloud endpoint
  • ❌ agent endpoint

​
Date format

Use the format “Month Day, Year” for dates. Do not use numeric formats or day-first formats.
  • ✅ July 31, 2016
  • ✅ December 25, 2023
  • ❌ 7/31/2016
  • ❌ 31/7/2016
  • ❌ 7.31.2016
  • ❌ 31 July 2016

​
Description field required

Every document must include a description field in the frontmatter. The description should be approximately 150 characters long and end with a period. 
---
title: Getting Started
✅ description: Learn how to get started with ngrok and create your first tunnel.
---

---
title: Getting Started
❌
---

​
Ellipses

Don’t use three periods (...) as an ellipsis. If you need to reference UI text that contains an ellipsis, use the single-character ellipsis (…).
  • ✅ The dialog shows Continue… when ready.
  • ❌ The dialog shows Continue… when ready.
  • ❌ Wait for the process to complete…

​
Dash spacing

Don’t put spaces before or after an em dash or en dash.
  • ✅ The feature is available—check the settings.
  • ✅ Use ngrok—it’s fast and secure.
  • ❌ The feature is available — check the settings.
  • ❌ Use ngrok — it’s fast and secure.

​
Exclamation points

Don’t use exclamation points in documentation. Keep the tone professional and calm.
  • ✅ This feature is now available.
  • ❌ This feature is now available!

​
First-person pronouns

Avoid first-person pronouns (I, me, my, mine, we, our, us, let’s). Speak directly to the reader using “you” instead.
  • ✅ You can configure the settings.
  • ✅ To get started, follow these steps.
  • ❌ We recommend using this approach.
  • ❌ Let’s configure the settings.
  • ❌ Our application will receive the request.

​
Gender-neutral pronouns

Don’t use gender-specific pronouns like “he/she” or “s/he”. Use gender-neutral alternatives like “they” or “them”.
  • ✅ The user can configure their settings.
  • ✅ Each developer should update their code.
  • ❌ The user can configure his/her settings.

​
Heading capitalization

While titles (h1) use title case, all other headings (h2-h6) use sentence case. Capitalize the first word and proper nouns (such as ngrok-specific terms) only.
  • ✅ Getting started with ngrok
  • ✅ Configure your API key
  • ✅ Using Traffic Policies
  • ❌ Getting Started With Ngrok
  • ❌ Configure Your API Key
  • ❌ Using traffic policies

​
Heading punctuation

Don’t put periods at the end of headings.
  • ✅ Getting started
  • ❌ Getting started.

​
Latin abbreviations

Replace Latin abbreviations with plain English.
Why? Latin abbreviations are commonly misused (for example, using “i.e.” when you really mean “e.g.”) and not always understood by non-native English speakers.
  • ✅ For example, you can use this method.
  • ✅ That is, the configuration must be updated.
  • ❌ e.g., you can use this method.
  • ❌ i.e., the configuration must be updated.
  • ❌ eg, you can use this method.
  • ❌ ie, you can use this method.

​
Hyphens after -ly words

Don’t use hyphens after words ending in “-ly”.
  • ✅ The recently updated feature
  • ✅ A quickly running process
  • ✅ The newly created account
  • ❌ The recently-updated feature
  • ❌ A quickly-running process
  • ❌ The newly-created account

​
Optional plurals

Don’t use optional plurals in parentheses like “user(s)”. Choose either singular or plural based on context.
  • ✅ The user can configure settings.
  • ✅ Users can configure settings.
  • ✅ Select the option you need.
  • ❌ The user(s) can configure settings.
  • ❌ Select the option(s) you need.

​
Oxford comma

Always use the Oxford comma (serial comma) in lists of three or more items.
  • ✅ You can use ngrok, Cloudflare, or AWS.
  • ✅ The options include red, blue, and green.
  • ✅ Configure the API, database, and cache.
  • ❌ You can use ngrok, Cloudflare or AWS.
  • ❌ The options include red, blue and green.
  • ❌ Configure the API, database and cache.

​
Periods with acronyms

Don’t use periods with acronyms or initialisms.
  • ✅ API
  • ✅ HTTP
  • ✅ HTTPS
  • ✅ DNS
  • ✅ CLI
  • ❌ A.P.I.
  • ❌ H.T.T.P.
  • ❌ H.T.T.P.S.
  • ❌ D.N.S.
  • ❌ C.L.I.

​
Sentence spacing

Use exactly one space after sentence-ending punctuation (period, question mark, exclamation point).
  • ✅ This is a sentence. This is another sentence.
  • ❌ This is a sentence. This is another sentence. (two spaces)
  • ❌ This is a sentence.This is another sentence. (no space)

​
American spelling

Use American spelling instead of British spelling.
  • ✅ organized
  • ✅ color
  • ✅ center
  • ✅ labor
  • ❌ organised
  • ❌ colour
  • ❌ centre
  • ❌ labour