This article serves as the primary entry-point all things documentation-related.
- If you have an idea to improve the docs tooling, submit a ticket over in the Next repo.
- If you have an idea to improve the docs (an article, post, example, etc.), submit a ticket over in the Teleport repo.
- Often thankless. Often neglected, it can make or break teams when they encounter a stumbling block.
- Hard. Without structure, over time, it turns into a random collection of articles.
- Essential when learning - whether one's a new or a seasoned engineer.
- Often the final arbiter of disputes and disagreements. Reference documentation is often the ultimate source of truth about a product, service, or tool.
- At best: an arm of Engineering, an advocate for developers, enpowerment for learning, and definitive resolution for customers.
- At worst: a disorganized morass of inaccurate and unhelpful jargon.
- Supplements other support mediums like Stack Overflow, support forums, GitHub issues, Slack, and so on. There are many customer voices and we want to hear them all. As such, we provide several avenues for expression, questions, and feedback.
- Not marketing although it plays a role in onboarding customers. Page views matter, but accuracy and customer satisfaction matter most.
- Often essential to leadership when they're evaluating a product. Doubly so when potential customers are in high-regulation spaces like finance or government. Many teams neglect their documentation only to fail to secure (or have delayed) the lucrative contracts that such potential customers can bring.
This section ennumerates the most-common kinds of documents we write at Teleport and include within our document set.
Getting started guides are self-contained, quickstart, articles and should aim to get a user up and running in the shortest way.
- These are Tutorials in DIVIO parlance, articles designed for beginners, and often people who may not have heard about Teleport before. This is one of the first interactions they'll have with the product so we want it to be stress-free and fun.
- We should strive to preclude anything that breaks the reader's focus or their ability to complete the sequence (missing code, incomplete examples, something they can't just copy-paste).
- A good quickstart takes 5-10 minutes, states the utility of completing the article at the beginning, and a demo video.
- Getting started title:
"SSO and Audit for Kubernetes in 3 steps"
- Followed by a demo video.
- Prerequisites and tools used should go next.
- Several sub-sections describing a concrete, completable, portion of the Tutorial sequence.
- Wrap up with "Next steps" section.
Getting started guides should be written with the goal to keep a busy user engaged.
Each step is clearly stated so users can easily follow the sequence: "Step 1 out of 3. Adding a local user."
Guides are self-contained articles for intermediate readers (readers with some familiarity working with Teleport already) setting up Teleport for a specific scenario.
These are How-To's in DIVIO parlance. They describe a way to use Teleport for a specific purpose. Here, conceptual information is deprioritized and the hand-on ability to complete the objective is made paramount.
- Guide title: "Kubernetes Access on GKE" which features a High Availability setup using Firebase and GCS backend.
- Followed by the guide purpose.
- Followed by prerequisites.
- Next, the setup steps.
- Wrap up with "Next steps" section.
It's OK to have duplicate content between different guides. In many cases this is encouraged for ease and familiarity.
Readers should be able to scroll down the guide and get to the end without leaving the page. Do not use an anchor or HTML link to describe some step - concisely, include the steps within the guide.
Specific kinds of guides include:
- Integration - integration guides explain how to set up Teleport with other tools. E.g. - "Access Requests with Slack".
- Best Practices - best practices guides are about best deployment and usage practices. They sometimes describe common patterns and anti-patterns.
- Troubleshooting - troubleshooting guides list common failures and how to diagnose them, they explain logs, remedies and tips and tricks.
Architecture articles explain how Teleport works to advanced readers. Architects, devsecops, or similar professional constitute the most-common audience.
- These are (partly) Concepts in DIVIO parlance. They describe high-level concepts with a narrowed focus on architectural concerns.
- These articles are therefore used to evaluate architectural decisions, configuration, and use-scenarios.
Specific kinds of architecture articles 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. Make sure to include these sections when appropriate!
- Deployment - should include a deployment diagram which in turn explains components and how they interact with databases and each other.
These articles comprehensively ennumerate Concepts (in DIVIO parlance) from the perspective of a user or admin.
- We should think of these not as How-To's but as continuations of our Architectural article work.
- Whereas the former is concerned with how to use, find, or create something using Teleport tools, the latter is concerned with the interaction of containers, nodes, security, and infrastructure.
- Some overlap will be likely between admin and Architecture articles.
Reference manuals provide an exhaustive list of configuration options and API methods (reference documentation).
- HTML or Markdown tables are often the best formats for this kind of article (or sections within them).
- A good reference manual is search friendly and lists all content on the same page.
- These should avoid prose and be expressed with great brevity in a dry, crisp, and accurate manner.
- Read more about content best practices.