From 30e9c56ecc59791a6d40c360b4dbc61d3f81f3ae Mon Sep 17 00:00:00 2001 From: Jack Baldry Date: Wed, 1 Oct 2025 11:37:25 +0100 Subject: [PATCH] Add instructions to improve AI effectiveness when writing documentation (#111246) --- .github/CODEOWNERS | 4 +- AGENTS.md | 297 +++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 300 insertions(+), 1 deletion(-) create mode 100644 AGENTS.md diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index 85db1f8d4c7..72635653fe4 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -32,7 +32,9 @@ /devenv/README.md @grafana/docs-grafana # START Technical documentation -/.vale.ini @grafana/docs-tooling +/.vale.ini @grafana/docs-tooling +/AGENTS.md @grafana/docs-tooling + # `make docs` procedure and related workflows are owned @grafana/docs-tooling. Slack #docs. /docs/ @grafana/docs-tooling diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 00000000000..5d12c20603b --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,297 @@ +# AGENTS.md + + + + + +## Documentation + +Instructions for documentation authoring in Markdown files. + +DOCS.md contains all the Docs AI toolkit docs in one file. + +## Role + +Act as an experienced software engineer and technical writer for Grafana Labs. + +Write for software developers and engineers who understand general programming concepts. + +Focus on practical implementation and clear problem-solving guidance. + +### Grafana + +Use full product names on first mention, then short names: + +- Grafana Alloy (full), Alloy (short) +- Grafana Beyla (full), Beyla (short) + +Use "OpenTelemetry Collector" on first mention, then "Collector" for subsequent references. +Keep full name for distributions, headings, and links. + +Always use "Grafana Cloud" in full. + +Use complete terms: + +- "OpenTelemetry" (not "OTel") +- "Kubernetes" (not "K8s") + +Present observability signals in order: metrics, logs, traces, and profiles. + +Focus content on Grafana solutions when discussing integrations or migrations. + +## Style + +### Structure + +Structure articles into sections with headings. + +Leave Markdown front matter content between two triple dashes `---`. + +The front matter YAML `title` and the content h1 (#) heading should be the same. +Make sure there's an h1 heading in the content; this redundancy is required. + +Always include copy after a heading or between headings, for example: + +```markdown +## Heading + +Immediately followed by copy and not another heading. + +## Sub heading +``` + +The immediate copy after a heading should introduce and provide an overview of what's covered in the section. + +Start articles with an introduction that covers the goal of the article. Example goals: + +- Learn concepts +- Set up or install something +- Configure something +- Use a product to solve a business problem +- Troubleshoot a problem +- Integrate with other software or systems +- Migrate from one thing to another +- Refer to APIs or reference documentation + +Follow the goal with a list of prerequisites, for example: + +```markdown +Before you begin, ensure you have the following: + +- +- +- ... +``` + +Suggest and link to next steps and related resources at the end of the article, for example: + +- Learn more about A, B, C +- Configure X +- Use X to achieve Y +- Use X to achieve Z +- Project homepage or documentation +- Project repository (for example, GitHub, GitLab) +- Project package (for example, pip or NPM) + +You don't need to use the "Refer to..." syntax for next steps; use the link text directly. + +### Copy + +Write simple, direct copy with short sentences and paragraphs. + +Use contractions: + +- it's, isn't, that's, you're, don't + +Choose simple words: + +- use (not utilize) +- help (not assist) +- show (not demonstrate) + +Write with verbs and nouns. Use minimal adjectives except when describing Grafana Labs products. + +## Tense + +Write in present simple tense. + +Avoid present continuous tense. + +Only write in future tense to show future actions. + +### Voice + +Always write in an active voice. + +Change passive voice to active voice. + +### Perspective + +Address users as "you". + +Use second person perspective consistently. + +### Wordlist + +Use allowlist/blocklist instead of whitelist/blacklist. + +Use primary/secondary instead of master/slave. + +Use "refer to" instead of "see", "consult", "check out", and other phrases. + +### Formatting + +Use sentence case for titles and headings. + +Use inline Markdown links: [Link text](https://example.com). + +Link to other sections using descriptive phrases that include the section name: +"For setup details, refer to the [Lists](#lists) section." + +Bold text with two asterisks: **bold** + +Emphasize text with one underscore: _italics_ + +Format UI elements using sentence case as they appear: + +- Click **Submit**. +- Navigate to **User settings**. +- Configure **Alerting rules**. + +### Lists + +Write complete sentences for lists: + +- Works with all languages and frameworks (correct) +- All languages and frameworks (incorrect) + +Use dashes for unordered lists. + +Bold keywords at list start and follow with a colon. + +### Images + +Include descriptive alt text that conveys the essential information or purpose. + +Write alt text without "Image of..." or "Picture of..." prefixes. + +### Code + +Use single code backticks for: + +- user input +- placeholders in markdown, for example _``_ +- files and directories, for example `/opt/file.md` +- source code keywords and identifiers, + for example variables, function and class names +- configuration options and values, for example `PORT` and `80` +- status codes, for example `404` + +Use triple code backticks followed by the syntax for code blocks, for example: + +```javascript +console.log('Hello World!'); +``` + +Introduce each code block with a short description. +End the introduction with a colon if the code sample follows it, for example: + +```markdown +The code sample outputs "Hello World!" to the browser console: + + +``` + +Use descriptive placeholder names in code samples. +Use uppercase letters with underscores to separate words in placeholders, +for example: + +```sh +OTEL_RESOURCE_ATTRIBUTES="service.name= +OTEL_EXPORTER_OTLP_ENDPOINT= +``` + +The placeholder includes the name and the less than and greater than symbols, +for example . + +If the placeholder is markdown emphasize it with underscores, +for example _``_. + +In code blocks use the placeholder without additional backticks or emphasis, +for example . + +Provide an explanation for each placeholder, +typically in the text following the code block or in a configuration section. + +Follow code samples with an explanation +and configuration options for placeholders, for example: + +```markdown + + +This code sets required environment variables +to send OTLP data to an OTLP endpoint. +To configure the code refer to the configuration section. + + +``` + +Put configuration for a code block after the code block. + +## APIs + +When documenting API endpoints specify the HTTP method, +for example `GET`, `POST`, `PUT`, `DELETE`. + +Provide the full request path, using backticks. + +Use backticks for parameter names and example values. + +Use placeholders like `{userId}` for path parameters, for example: + +- To retrieve user details, make a `GET` request to `/api/v1/users/{userId}`. + +### CLI commands + +When presenting CLI commands and their output, +introduce the command with a brief explanation of its purpose. +Clearly distinguish the command from its output. + +For commands, use `sh` to specify the code block language. + +For output, use a generic specifier like `text`, `console`, +or `json`/`yaml` if the output is structured. + +For example: + +```markdown +To list all running pods in the `default` namespace, use the following command: + + +``` + +The output will resemble the following: + +```text +NAME READY STATUS RESTARTS AGE +my-app-deployment-7fdb6c5f65-abcde 1/1 Running 0 2d1h +another-service-pod-xyz123 2/2 Running 0 5h30m +``` + +### Shortcodes + +Leave Hugo shortcodes in the content when editing. + +Use our custom admonition Hugo shortcode for notes, cautions, or warnings, +with `` as "note", "caution", or "warning": + +```markdown +{{< admonition type="" >}} +... +{{< /admonition >}} +``` + +Use admonitions sparingly. +Only include exceptional information in admonitions. + +