- Version 15.x
- Version 14.x
- Version 13.x
- Version 12.x
- Older Versions
- Available for:
To keep our documentation effective as Teleport develops, we need to ensure that we maintain a consistent approach to organizing information.
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.
- How-to guides: Tutorials for intermediate readers who want to set up Teleport for a specific scenario.
- Getting started articles: Designed to get the user up and running in the quickest way possible.
- 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.
How-to guides are for readers who already have some familiarity with Teleport and want to set up Teleport for a specific scenario.
The introductory section should state the utility of completing the article.
Do not recreate content across guides when it is possible to refer a reader to a single, separate guide. Actions that are prerequisites to several topics but not directly related to those topics should be documented in a single location and referenced in a Prerequisites section at the top of the page.
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.
You can include a link in the body text of a how-to guide as long as you tell the reader why to follow the link and what information to glean from it. "Follow the installation instructions in the AWS documentation" does this, while "Read the AWS documentation for more information" does not.
Example code and configurations should be complete and pastable.
Each step is clearly stated so users can easily follow the sequence. Section headings should have a format similar to "Step 1/3. Add a local user"
- Guide title: "Access Kubernetes on GKE"
- The purpose of the guide
- Setup steps
- Next steps
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.
"Getting started" is a better term than "Quickstart". Google "Getting started with React" vs. "React quickstart" and compare the search results.
Getting started articles have the same expectations as how-to guides, plus the following:
- It should be possible to complete the tutorial in 5–10 minutes.
- Consider including a demo video in order to reach readers who prefer video.
- 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.
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:
- Networking: Readers are interested in learning about specific ports, components, and protocols that are or can be used.
- Security: Lists security protocols and primitives. SecOps will look for an attack vector tree diagram.
- Deployment: Should include a deployment diagram which in turn explains components and how they interact with databases and each other.
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 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.
- 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.
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.
If a commonly debated style question does not have a resolution in this guide (e.g., the Oxford comma), all we ask is that you keep your style consistent within a particular page to maintain a professional polish.
The documentation should be technically precise and directed toward a technical audience, e.g., application developers, site reliability engineers, and security engineering team leads.
Even when describing Teleport generally, we should emphasize specific technical capabilities over broad statements of benefit. The aim is not to pique the audience's interest, but to provide information.
For example, rather than:
Teleport replaces insecure secrets with true identity.
Teleport replaces shared secrets with short-lived X.509 and SSH certificates.
Some guides are intended for end users seeking to access resources in their cluster. For certain use cases, it may be necessary to adjust our usual voice for the audience of a specific guide.
- 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.
tctl, and other core commands should be placed in backticks.
All ports or values should be enclosed in backticks, e.g.,
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."
- Use Teleport's lucidchart library to create diagrams with a consistent design language.
- Diagram multistep sections using sequence diagrams that depict steps linearly.
- Several great examples are available here: https://gravitational.slab.com/posts/diagrams-ix9nzhpd.
- Footnotes should be ordered by appearance (chronological precedence).
2should not come before
- 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.
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.
- 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.
- 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.
- Should have all words capitalized except for determiners (
- Should follow a
Title Name | Teleport Docsformat. The
| Teleport Docssuffix 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.
- Make sure to have a good, well-worded description that uses common keywords around the subject. Also, liberally sprinkle said keywords throughout the article.
Mac users should use Quicktime's
Cmd-Shift-5to record a small part of the screen:
Quicktime outputs large
ffmpegto convert them into
create MP4ffmpeg -i input.mov -b:v 0 -crf 25 output.mp4
create WebMffmpeg -i input.mov -c vp9 -b:v 0 -crf 41 output.webm