Fork me on GitHub

Teleport

Style Guide

Improve

To keep our documentation effective as Teleport develops, we need to ensure that we maintain a consistent approach to organizing information.

Kinds of pages

Each documentation page at Teleport falls into one of five categories. Each page is self contained, and it is okay have duplicate content between different guides. This is encouraged to promote familiarity with the product.

  • Getting started articles: Designed to get the user up and running in the quickest way possible.
  • How-to guides: Tutorials for intermediate readers who want to set up Teleport for a specific scenario.
  • Architecture guides: Guides that explain how Teleport works to advanced readers, e.g., architects, DevSecOps engineers, and SREs.
  • Conceptual guides: Explain concepts related to Teleport for users who want a deeper understanding of its functionality.
  • Reference manuals: Provide a comprehensive list of configuration options, API methods, metrics, and other ways of interacting with Teleport.

Getting started articles

Getting started guides are designed to get a user up and running in the shortest way possible. They are intended for first-time Teleport users, and are often one of the first interactions they will have with the product. They should be fun and stress free.

Note

"Getting started" is a better term than "Quickstart". Google "Getting started with React" vs. "React quickstart" and compare the search results.

Expectations

  • The introductory section should state the utility of completing the article.
  • It should be possible to complete the tutorial in 5–10 minutes.
  • Do not break the reader's focus. Do not link the reader to another page—or even another section within the same page—when it is possible to include the same content in the current paragraph or section.
  • Example code and configurations should be complete and pasteable.
  • The page should include a demo video.
  • Each step is clearly stated so users can easily follow the sequence. Sections headings should have a format similar to, "Step 1/3 Add a local user"

Example outline

  • Title: "SSO and Audit for Kubernetes in three steps"
  • Demo video
  • Prerequisites section: lists the tools used in the guide
  • Several sub-sections describing concrete steps that a user can verify they have completed
  • Wrap up with "Next steps" section.

How-to guides

How-to guides are for readers who already have some familiarity with Teleport and want to set up Teleport for a specific scenario.

Expectations

  • The introductory section should state the utility of completing the article.
  • Do not break the reader's focus. Do not link the reader to another page—or even another section within the same page—when it is possible to include the same content in the current paragraph or section.
  • Example code and configurations should be complete and pastable.
  • Each step is clearly stated so users can easily follow the sequence. Sections headings should have a format similar to, "Step 1/3 Add a local user"

Example outline

  • Guide title: "Kubernetes Access on GKE"
  • The purpose of the guide
  • Prerequisites
  • Setup steps
  • Next steps

Architecture guides

Architecture guides explain how Teleport works to advanced readers, e.g., architects, DevSecOps engineers, and SREs. They describe high-level concepts with a narrow focus on architectural concerns, and are used to evaluate architectural decisions, configuration, and usage scenarios.

Specific kinds of architecture guides include:

  1. Networking: Readers are interested in learning about specific ports, components, and protocols that are or can be used.
  2. Security: Lists security protocols and primitives. SecOps will look for an attack vector tree diagram.
  3. Deployment: Should include a deployment diagram which in turn explains components and how they interact with databases and each other.

Conceptual guides

Conceptual guides are a continuations of our architectural guides and distinct from how-to guides. They explain a concept that is relevant for understanding Teleport. Some overlap will be likely between conceptual guides and architecture guides.

Reference manuals

Reference manuals provide an exhaustive list of configuration options, API methods, and other possible fields and values for the various ways in which users can interact with Teleport.

Expectations

  • Should be comprehensive. If listing configuration options, API paths, and so on, list all of them, rather than a few examples.
  • HTML or Markdown tables are often the best formats for this kind of article .
  • Should be easy to navigate with a browser's search functionality. List all content on the same page.
  • Should avoid prose and be expressed with brevity.

General style rules

Please refer to this style guide when determining how address questions about English grammar, usage, and so on. Since many of these rules have equally justifiable alternatives, a style guide prevents debates over these questions from getting in the way of documenting Teleport.

Body text

  • Write sparser one to two-sentence groupings rather than lengthier blocks of text.
  • Use periods at the end of a line even in a list unless the ending item is a command.

Code, commands, and configuration

  • tsh, tctl, and other core commands should be placed in backticks.

  • All ports or values should be enclosed in backticks, e.g., 443.

  • Prefer putting commands (e.g., Bash scripts) into full-line code snippets. These will render with a handy copy button.

    echo "This is an example."

Diagrams

Footnotes

  • Footnotes should be ordered by appearance (chronological precedence). 2 should not come before 1.

Headings

  • Headings should be in sentence case. For example, "Next steps" is preferred over "Next Steps." We want to clarify proper nouns and products in headings by using sentence casing.

Lists

  • We prefer short paragraph blocks over bulleted or numbered lists. This leads to a preference for completeness and brevity rather than enumeration.

  • When you do include a list, we prefer bullet points over numbered lists.

  • Use numbered lists for any sequence of steps, but use these sparingly.

    Each number should mention the total number of steps, e.g., "Step 1/5," so the reader knows how far along they are in the sequence.

Names of products, services, and features

  • Product proper nouns should be capitalized. Say "Trusted Cluster," not "trusted cluster."
  • Avoid using quotes to refer to product names, since they often have negative connotations. E.g, do not say, "Trusted Cluster."
  • Product proper nouns should be bolded on first use. "Trusted Cluster" should be Trusted Cluster.

Names of technical concepts

  • Within a single page, use consistent acronyms and concept keywords. For example, pick one of "2-factor," "two-factor", "2fa," or "tfa" within a given page.
  • Acronyms should always be introduced following a concept keyword and then consistently used thereafter.

Page titles

  • Should have all words capitalized except for determiners (a, the, etc.).
  • Should follow a Title Name | Teleport Docs format. The | Teleport Docs suffix will be added automatically by our static site generator.
  • The total character count should not exceed 70 for the entire title since this can impact SEO. Including the suffix | Teleport Docs, that leaves 55 characters for the article's title.

SEO

  • Make sure to have a good, well-worded description that uses common keywords around the subject. Also, liberally sprinkle said keywords throughout the article.

Videos

  • Mac users should use Quicktime's Cmd-Shift-5 to record a small part of the screen:

    quicktime

  • Convert .mov videos to .mp4 and webm.

    Quicktime outputs large .mov files. Use ffmpeg to convert them into mp4 and webm web-friendly formats:

    create MP4

    ffmpeg -i input.mov -b:v 0 -crf 25 output.mp4

    create WebM

    ffmpeg -i input.mov -c vp9 -b:v 0 -crf 41 output.webm