opensource/teleport
3
0
Fork 0
mirror of https://github.com/gravitational/teleport.git synced 2026-08-28 21:12:20 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs: Add docs-review guidelines AGENTS.md (#67631)

Browse Source 
* docs: Add docs-review guidelines AGENTS.md

* Address review feedback - backport-awareness guidance, check for internal inconsistency within pages, point agents to the docs-website remark-lint config, normalize list markers and nesting in both files

* feedback entries: claude.md addition (rodgtr1) and documentation-style-guide.md (ptgott)

* re-theme AGENTS-STYLE.md as a review guide; dedupe with style guide

* post-feedback from Codex: correcting relative path to contributing file
This commit is contained in:
mica
2026-07-01 18:25:28 -07:00
committed by GitHub
parent aa59f5172f
commit 044a714228
4 changed files with 559 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/AGENTS-STYLE.md
+77
View File
@@ -0,0 +1,77 @@
# Reviewing docs for style (agent guide)
This file tells an AI agent **how to apply** Teleport's documentation
conventions when reviewing a docs PR. It deliberately does not restate the
conventions themselves: those live in
[`../contributing/documentation-style-guide.md`](../contributing/documentation-style-guide.md),
the single source of truth shared by human contributors and agents. When a
question isn't answered there, consistency within the page wins — do not flag
it.
For the review process, output format, and severity labels, see
[`AGENTS.md`](./AGENTS.md). This file covers the style/prose dimension
specifically.
## Before flagging a style issue
- **Check it against the style guide; don't assert from memory.** If a rule
isn't in `documentation-style-guide.md`, it isn't a rule. Do not invent
conventions or carry them in from other projects.
- **Don't duplicate the linters.** remark-lint (formatting, spacing, line
length) and Vale (word choice, prose style, spelling, banned terms) already
run in CI. Never raise a finding that one of those tools enforces — it's
noise. Spend review effort on what a linter can't judge: structure, voice,
internal consistency, and correctness.
- **Prefer no finding on judgment calls.** Voice and component choice need
judgment (see below). Raise these only when the violation is clear, and as a
Suggestion or Nit — never a Blocker.
## What an agent can check reliably vs. what needs a human
Check with confidence (flag when violated):
- Heading case (sentence case).
- Internal consistency within a page: a term capitalized or formatted two
ways, or an acronym/keyword that switches forms ("two-factor" vs. "2FA").
- Product proper nouns wrapped in quotes, or not capitalized.
- Page-title length over the 55-character budget (before the
"| Teleport Docs" suffix).
- List-item punctuation (period unless the item ends in a command).
Needs judgment (raise tentatively, or defer to a human):
- Whether the voice is appropriately technical for the page's audience.
- Whether a component (`Tabs`, `Details`, `Admonition`) earns its place or
should be prose or subheadings.
- Whether the page is the right *type* (how-to vs. tutorial vs. reference) for
its content.
## Severity defaults for style findings
Apply the severity labels from `AGENTS.md` as follows:
- **Blocker:** essentially never for pure style. Style issues don't block a
merge.
- **Suggestion:** a clear convention violation with an unambiguous fix — a
Title-Case heading, an inconsistent term, a command missing backticks.
- **Nit:** minor polish the author may ignore — a product noun not bolded on
first use, a title near the length ceiling.
## Page-type shape
The required shape of each page type (how-to, tutorial, conceptual, reference)
is defined in `documentation-style-guide.md`. Use it as a checklist, but only
flag a *missing* structural element when the PR adds a new page or heavily
rewrites the introduction, per the diff-context rule in `AGENTS.md`. Don't
assume an element is absent just because it falls outside the diff.
## Frontmatter and tags (verification discipline)
- Every standalone page (not an `includes/` partial) needs `title` and
`description`. The `description` is one sentence that starts with a verb and
ends with a period.
- **Do not invent or "correct" tag names.** The canonical lists of valid
frontmatter fields and tags live in the docs-website repo
(`frontmatter_fields.yaml`, `tags.yml`), not here. If a tag looks
unfamiliar, flag it for human verification against `tags.yml` rather than
guessing a "right" value.
docs/AGENTS.md
+142
View File
@@ -0,0 +1,142 @@
# AGENTS.md
Guidance for AI agents reviewing documentation PRs in this repo. Docs live in
`docs/pages/` and are written in MDX. These guidelines apply to changes under
`docs/`; for code changes, see the repo-root `AGENTS.md`.
## Review guidelines
- Focus on accuracy, structure, and conventions. Flag issues; do not rewrite.
- Keep suggestions targeted. Quote the specific line and propose a minimal fix.
- Flag only issues that affect correctness, conventions, or reader success.
Do not report stylistic preferences beyond the rules listed here and in
`AGENTS-STYLE.md`.
- **Diff context limitations:** Only flag missing structural elements (like
Prerequisites or "How it works" sections) if the PR is adding a completely
new page or heavily rewriting the introduction. Do not flag missing elements
if they might exist outside the provided diff context.
- When uncertain, prefer no finding over a speculative finding.
- Do not infer repo conventions that are not documented in this file or
`AGENTS-STYLE.md`.
- Docs changes on `master` are backported to release branches. Raise all
issues on the original PR; do not defer findings to the backport phase. A
finding that only surfaces during backport is a review miss.
## Review output
- Group findings by file, in the order files appear in the diff.
- Label each finding with a severity:
- **Blocker**: factual error, broken link, command that will not run as
written, or missing required frontmatter.
- **Suggestion**: convention violation, structural issue, or missing
recommended pattern with a clear fix.
- **Nit**: minor wording or formatting; authors may ignore these.
- For each finding, quote the line, state the issue in one sentence, and
propose the minimal fix. Use a GitHub suggestion block when the fix is a
one-line change.
- If the diff is clean, say so briefly. Do not invent findings.
Example of a well-formed finding:
> **Suggestion** (`docs/pages/admin-guides/example.mdx`, line 42):
> `## Configure The Agent` - headings use sentence case.
> Proposed fix:
> ```suggestion
> ## Configure the agent
> ```
## What to check
- **Style and conventions**
- The conventions themselves (voice, headings, naming, components, page-type
shape, and so on) live in
[`contributing/documentation-style-guide.md`](contributing/documentation-style-guide.md),
the single source of truth shared with human contributors. Do not restate
or re-derive those rules — consult the guide.
- For how to *apply* them in review — what an agent can check reliably, what
the linters already cover, and how to rate severity — see
[`AGENTS-STYLE.md`](./AGENTS-STYLE.md).
- Beyond the guide, flag internal inconsistency within a page: the same term
capitalized or formatted two ways, or an acronym/concept keyword that
switches forms (e.g. "two-factor" in one place, "2FA" in another).
- Code fences declare a language and follow repo conventions (e.g., `code`
for commands, `yaml` for config).
- Admonitions (`<Admonition>`) are used for warnings and notes, not for
content that belongs in body text.
- **Structural patterns**
- How-to guides include a `How it works` section after the introduction.
- A Prerequisites block appears before the first step.
- Steps use `Step N/M.` numbered headings. *Note: Verify that step numbers
are sequential within the diff. Flag obvious numbering errors, but defer to
human review for the total step count (the `M` value) if the whole file is
not visible.*
- Checkpoint blocks appear at genuine verification gates. A Checkpoint
belongs after a step whose silent failure would break later steps. Do not
require checkpoints after every step; use them only where verification
materially reduces troubleshooting effort. Titles state a positive success
condition; bodies contain only troubleshooting guidance.
- **Version scoping**
- Commands, config fields, and flags exist in the Teleport version the page
targets. The target version is the release line of the branch the PR is
based on (`master` targets the next release; `branch/v*` targets that
major version). *(Note: The target branch will be provided in your system
prompt context.)*
- To verify a command or flag exists, check the CLI reference pages in this
repo: `docs/pages/reference/cli/tctl.mdx`,
`docs/pages/reference/cli/tsh.mdx`, and
`docs/pages/reference/cli/tbot.mdx` (published under
`https://goteleport.com/docs/reference/cli/`). If you cannot verify, flag
uncertainty for a human reviewer; do not assert that a flag exists or does
not exist from memory.
- Version-specific behavior is called out explicitly.
- **LLM-readability**
- Commands are copy-pastable as written.
- User-supplied values are marked with `<Var>` components (e.g.,
`<Var name="username" />`). Reused values should generally use the same
`<Var>` component consistently throughout the page.
- Partials/includes are used where shared content exists. Partials live in
`docs/pages/includes/`; before flagging duplication, confirm a matching
partial actually exists there.
- **Cross-references**
- Links to related docs are present and resolve (correct relative paths, no
broken anchors).
- Links to pages within this repo use relative `.mdx` paths rather than
published `https://goteleport.com/docs/...` URLs.
- `Next steps` sections link to canonical follow-on guides.
- **Frontmatter completeness**
- `title` and `description` are present and accurate. The `description` is
one sentence that starts with an active verb (e.g., "Explains how to...",
"Configures...") and ends with a period.
- For newly added standalone pages (files outside `includes/`), verify that
`tags` and `sidebar_label` are present.
- Canonical tag definitions live in the docs-website repo (`tags.yml`). Do
not invent or "correct" tag names; flag unfamiliar tags for human
verification. See the "Frontmatter and tags" section of `AGENTS-STYLE.md`.
## References
- Documentation conventions (source of truth):
[`contributing/documentation-style-guide.md`](contributing/documentation-style-guide.md),
shared with human contributors.
- Applying those conventions in review: [`AGENTS-STYLE.md`](./AGENTS-STYLE.md)
(next to this file) — what's checkable, what the linters cover, and severity
for style findings.
- CLI references: `docs/pages/reference/cli/{tctl,tsh,tbot}.mdx`.
- Automated linting: docs content is checked by remark-lint in the
docs-website repo (`.remarkrc.mjs`, run via `yarn markdown-lint` in CI). Do
not spend review effort on mechanical issues these rules catch automatically
(e.g. formatting, line length); focus on accuracy, structure, and
conventions the linter cannot verify. Do not attempt to build or lint docs
from this repo.
## Out of scope
Do not do the following in a docs review:
- Wholesale rewrites on style or tone grounds.
- Changes to product behavior described in the docs. If the docs appear to
contradict product behavior, flag it for a human reviewer.
- Auto-resolving MDX includes (`(!...!)` partials) into inline content.
- Speculation on provider-specific facts (AWS, Azure, GCP, IdP vendors)
without a source. Flag uncertainty for a human reviewer instead.
- Verifying commands against live clusters.
docs/CLAUDE.md
+8
View File
@@ -0,0 +1,8 @@
<!--
Claude Code reads CLAUDE.md, not AGENTS.md. This file imports AGENTS.md so that
Claude Code and other agents share the same docs-review instructions without
duplicating them. Keep shared guidance in AGENTS.md; add any Claude-specific
notes below the import line.
-->
@AGENTS.md
docs/contributing/documentation-style-guide.md
+332
View File
@@ -0,0 +1,332 @@
# Teleport documentation style guide
This guide describes our approach to building effective documentation, the
conventions we follow, and the recommended practices for organizing, crafting,
and evolving our information architecture with a clear and consistent voice.
Many style rules have equally justifiable alternatives. Following a common
style guide is intended to prevent debates over style questions from getting in
the way of documenting Teleport. If you don't see an answer to a style question
in this guide, follow your best judgement and keep the style you choose
consistent within the page you're working on.
## Organizing information into purpose-driven documents
For software documentation, you can structure information using the following
information model:
- Tutorials are learning oriented and designed to give a newcomer a positive,
successful experience. Tutorials should be tested regularly to ensure they
don't get stale and that they always provide a successful result.
- How-to guides are task oriented with practical steps to achieve a specific
goal. These guides assume that readers are familiar enough with Teleport that
they know the task they want to complete for a specific scenario but not
necessarily how to complete it.
- References are information oriented technical descriptions of a system or its
components.
- Explanations are the conceptual framework for understanding how or why a
system works. Explanation provides the context that surrounds what people
learn in a tutorial, do in a how-to guide, or look up in reference material.
For more detailed information and examples of how to structure documentation
using this information model, see The Grand Unified Theory of Documentation.
## Structuring content into pages
In general, every page of documentation should have a purpose and be
self-contained. It's okay for information to be in multiple places and similar
content can exist in pages that serve different purposes. For example, you might
have conceptual information about trusted clusters in one page and have similar
content as context in a how-to topic. When possible, you should reuse content
rather than duplicate content, but it's perfectly fine to cover the same
information in more than one place to serve different purposes.
## How-to guides
A how-to guide describes how to achieve a goal or complete a task. Only the
information that is pertinent to achieving that goal or completing the task is
included. With how-to guides, readers have enough information to know what they
want to do; for example, open a bank account—but not necessarily enough
information to know how to do it. For example, the how-to guide for opening a
bank account wouldn't explain what a bank account is or why you might want to
open one, but would focus on specific steps such as:
1. Select an institution.
2. Fill out an application.
3. Deposit a minimum amount of currency.
How-to guides often include links to additional information, but should not
include explanations that take the focus away from what the reader wants to
accomplish.
### What's in a how-to guide?
In most cases, how-to guides contain the following sections:
- Frontmatter with a guide title, description, and other information. The title
should be short and identify the subject of the how-to topic in the fewest
words possible. The description should be a sentence that starts with a verb,
summarizes the content of the topic, and ends with a period. Additional
information might include a video banner link, a list of keywords, or an
alternate first-level heading.
- One or more introductory paragraphs that explain what the task-at-hand is,
the use case or scenario driving the reader to complete the task, and the
expected outcome.
- List of prerequisites. Actions that are common to multiple topics that must
be taken before starting the procedure in how-to topics are generally
documented in partial files and referenced in the list of prerequisites.
- Task step sections that break down the how-to procedure into manageable
chunks or subtasks with clearly-defined goals. Currently, task step sections
use headings that convey the current and total number of steps involved to
complete the procedure, for example, Step 1/3. Add a local user.
In most cases, task step sections include code examples, configuration
settings, and screenshots to illustrate the actions the reader should
perform. Whenever possible, readers should be able to copy and paste the
example code and configurations with minimal changes to complete the
procedure being documented.
- The "next steps" section can be used to add links to logically related
topics, if applicable, or to recommend related topics for further reading,
such as reference topics related to the procedure completed.
### Using links, admonishments, and details in how-to guides
You should avoid breaking the reader's focus in how-to guides. For example,
avoid adding links to other pages or to other sections in the same topic. Avoid
inserting notices, tips, admonishments, or collapsed details sections unless
absolutely necessary.
If you do include a link in a how-to guide to external documentation, be sure
to tell the reader why to follow the link and what information to glean from it.
For example, use explicit information like "Follow the installation instructions
in the AWS documentation" instead of "Read the AWS documentation for more
information".
## Tutorials
Tutorials are designed to give first-time Teleport users hands-on experience
completing a set of explicit instructions. Tutorials should be as simple and
straightforward as possible. Tutorials must provide a positive learning
experience and a successful outcome with no unexpected behavior or unexplained
errors. It's okay for a tutorial to include a red herring to illustrate a common
misstep but the author must provide a sufficient explanation of the error and
how to correct it.
### What's in a tutorial?
Tutorial or getting started guides contain much of the same content as how-to
guides but are focused on achieving learning objectives:
- Frontmatter with a demo video to reach readers who prefer video.
- One or more introductory paragraphs that explain what the tutorial
demonstrates.
- Before you begin, list the tools required to complete the tutorial.
- Learning objectives that summarize what the reader will accomplish by
completing the tutorial.
- Task steps that the reader must follow in sequence to successfully complete
the lesson.
- The "next steps" section can be used to add links to logically related topics,
if applicable, or to recommend related topics for further reading, such as
reference topics related to the procedure completed.
## Conceptual guides
Conceptual guides and architecture guides explain core concepts and how Teleport
works at system, component, and operational levels. Guides for conceptual and
architectural information can include the following types of topics:
- Networking for audiences interested in networking concepts, components, and
protocols.
- Security for audiences interested in security protocols, cryptographic
primitives, and reducing attack vectors.
- Deployment for audiences interested in deployment architecture.
### What's in a conceptual guide?
Conceptual guides typically contain the following sections:
- Frontmatter with a guide title, description, and other information. The title
should be short and identify the subject of the topic in the fewest words
possible. The description should be a sentence that starts with a verb,
summarizes the content of the topic, and ends with a period. Additional
information might include a list of keywords, or an alternate first-level
heading.
- Body paragraphs that explain concepts, components, system operations, and
context to help the reader understand what something is, why it's important,
and how it works.
- Diagrams to illustrate component relationships or flow of operations.
- Links to related topics, where applicable.
## 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.
- 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.
### What's in a reference manual?
Reference manuals typically contain the following sections:
- Frontmatter with a guide title, description, and other information. The title
should be short and identify the subject of the topic in the fewest words
possible. The description should be a sentence that starts with a verb,
summarizes the content of the topic, and ends with a period. Additional
information might include a list of keywords.
- One or more introductory paragraphs that explain what information the manual
covers.
- Formatted reference information. The format might resemble a man page or API
description with a common set of sections (name, description, syntax, options,
examples, and so on) or the format might use lists or tables to present
information.
- Links to related topics, where applicable.
## General style rules
Please refer to this style guide when determining how to 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.
### Use of frontend components
In general, we want pages in the documentation to emphasize text and provide an
uncluttered experience to readers. Before adding a component besides a
paragraph, heading, or example code snippet, ask what benefit the component adds
to a page, and if it is possible to achieve a similar result with only
paragraphs, headings, and code snippets.
For example, when adding a Tabs component, ask if it would make sense to add a
subheading instead of each TabItem. TabItems would be useful if only one
variation of the instructions you are adding is relevant to a reader, and the
other two would only add distraction. If all variations of the instructions are
useful, subheadings would make more sense.
### Voice
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.
Use:
> 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.
### 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 into full-line code snippets. These will render with a
handy copy button.
### Diagrams
- Use Teleport's Lucidchart library to create diagrams with a consistent design
language.
- Diagram multistep sections using sequence diagrams that depict steps linearly.
### 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.
> **Avoid repetitive prefixes in sidebar titles**
>
> When multiple pages share a common action or theme, avoid repeating that
> prefix in every sidebar title (for example, "Deploy on AWS," "Deploy on
> Azure," "Deploy on GCP," etc). Repetition makes navigation harder to scan and
> adds visual noise. Instead, create a higher-level heading or category such as
> Deployments, and nest the individual pages underneath ("AWS," "Azure," "GCP").
> This keeps titles concise, reduces redundancy, and makes the sidebar easier to
> navigate at a glance.
### 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.
- Convert .mov videos to .mp4 and webm. Quicktime outputs large .mov files. Use
ffmpeg to convert them into mp4 and webm web-friendly formats:
```bash
# 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
```