Skip to content

Commit c57ad3b

Browse files
heitortsergentheitortsergent
authored
Update AGENTS.md file, add prompt files (#2136)
* Update AGENTS.md Add repository instructions, optimize Docs AI prompt * Add Google and Grafana style guide prompt files
1 parent 57157f8 commit c57ad3b

File tree

3 files changed

+95
-238
lines changed

3 files changed

+95
-238
lines changed

‎.github/prompts/copy-edit-google.prompt.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
---
2+
agent: 'agent'
3+
model: Sonnet 4.5
4+
description: 'Copy edit source content for clarity, grammar, and style using the Google developer style guide'
5+
---
6+
Copy edit this file according to the Google developer style guide, improve grammar, and fix spelling.

‎.github/prompts/copy-edit-grafana.prompt.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
---
2+
agent: 'agent'
3+
model: Sonnet 4.5
4+
description: 'Copy edit source content for clarity, grammar, and style using the Grafana style guide'
5+
---
6+
Copy edit this file according to the Grafana style guide, improve grammar, and fix spelling.

‎AGENTS.md‎

Lines changed: 83 additions & 238 deletions
Original file line numberDiff line numberDiff line change
@@ -1,295 +1,140 @@
1-
<!-- docs-ai-begin -->
2-
3-
<!-- version: 1.2.0 -->
4-
5-
# Docs AI toolkit instructions
6-
7-
## Documentation
8-
9-
Instructions for documentation authoring in Markdown files.
10-
11-
## Role
12-
13-
Act as an experienced software engineer and technical writer for Grafana Labs.
14-
15-
Write for software developers and engineers who understand general programming concepts.
16-
17-
Focus on practical implementation and clear problem-solving guidance.
18-
19-
### Grafana
20-
21-
Use full product names on first mention, then short names:
22-
23-
- Grafana Alloy (full), Alloy (short)
24-
- Grafana Beyla (full), Beyla (short)
25-
26-
Use "OpenTelemetry Collector" on first mention, then "Collector" for subsequent references.
27-
Keep full name for distributions, headings, and links.
28-
29-
Always use "Grafana Cloud" in full.
30-
31-
Use complete terms:
32-
33-
- "OpenTelemetry" (not "OTel")
34-
- "Kubernetes" (not "K8s")
35-
36-
Present observability signals in order: metrics, logs, traces, and profiles.
37-
38-
Focus content on Grafana solutions when discussing integrations or migrations.
39-
40-
## Style
41-
42-
### Structure
43-
44-
Structure articles into sections with headings.
45-
46-
Leave Markdown front matter content between two triple dashes `---`.
47-
48-
The front matter YAML `title` and the content h1 (#) heading should be the same.
49-
Make sure there's an h1 heading in the content; this redundancy is required.
50-
51-
Always include copy after a heading or between headings, for example:
52-
53-
```markdown
54-
## Heading
55-
56-
Immediately followed by copy and not another heading.
57-
58-
## Sub heading
59-
```
60-
61-
The immediate copy after a heading should introduce and provide an overview of what's covered in the section.
62-
63-
Start articles with an introduction that covers the goal of the article. Example goals:
64-
65-
- Learn concepts
66-
- Set up or install something
67-
- Configure something
68-
- Use a product to solve a business problem
69-
- Troubleshoot a problem
70-
- Integrate with other software or systems
71-
- Migrate from one thing to another
72-
- Refer to APIs or reference documentation
73-
74-
Follow the goal with a list of prerequisites, for example:
75-
76-
```markdown
77-
Before you begin, ensure you have the following:
78-
79-
- <Prerequisite 1>
80-
- <Prerequisite 2>
81-
- ...
82-
```
83-
84-
Suggest and link to next steps and related resources at the end of the article, for example:
85-
86-
- Learn more about A, B, C
87-
- Configure X
88-
- Use X to achieve Y
89-
- Use X to achieve Z
90-
- Project homepage or documentation
91-
- Project repository (for example, GitHub, GitLab)
92-
- Project package (for example, pip or NPM)
93-
94-
You don't need to use the "Refer to..." syntax for next steps; use the link text directly.
95-
96-
### Copy
97-
98-
Write simple, direct copy with short sentences and paragraphs.
99-
100-
Use contractions:
101-
102-
- it's, isn't, that's, you're, don't
103-
104-
Choose simple words:
105-
106-
- use (not utilize)
107-
- help (not assist)
108-
- show (not demonstrate)
109-
110-
Write with verbs and nouns. Use minimal adjectives except when describing Grafana Labs products.
111-
112-
## Tense
113-
114-
Write in present simple tense.
115-
116-
Avoid present continuous tense.
117-
118-
Only write in future tense to show future actions.
119-
120-
### Voice
121-
122-
Always write in an active voice.
123-
124-
Change passive voice to active voice.
1+
# k6-docs Repository Guide
1252

126-
### Perspective
3+
## About
1274

128-
Address users as "you".
5+
Official documentation for **Grafana k6** load testing tool. Built with Hugo, deployed to <https://grafana.com/docs/k6/>.
1296

130-
Use second person perspective consistently.
7+
## Repository structure
1318

132-
### Wordlist
9+
**Key directories:**
13310

134-
Use allowlist/blocklist instead of whitelist/blacklist.
11+
- **`docs/sources/k6/`** - All documentation content
12+
- `next/` - Next major release docs
13+
- `v{VERSION}/` - Version-specific docs (for example, `v1.4.x`)
14+
- `{VERSION}/shared/` - Reusable content for `{{< docs/shared >}}` shortcode
15+
- **`scripts/`** - Maintenance scripts
16+
- `apply-patch` - Port changes between versions
17+
- `md-k6.py` - Validate and run code snippets
18+
- **`vale/styles/`** - Documentation linting rules
13519

136-
Use primary/secondary instead of master/slave.
20+
## Version management
13721

138-
Use "refer to" instead of "see", "consult", "check out", and other phrases.
22+
- **`next/`** - Upcoming major release features
23+
- **`v{MAJOR}.{MINOR}.x/`** - Released versions (highest number = "latest" on site)
13924

140-
### Formatting
25+
**Where to make changes:**
14126

142-
Use sentence case for titles and headings.
27+
- **Current release**: Update both `next/` and `v{LATEST_VERSION}/`, then use `scripts/apply-patch HEAD~ docs/sources/k6/next docs/sources/k6/v1.4.x`
28+
- **Next release only**: Update `next/` only
29+
- **Bug fixes**: Use `apply-patch` to port to latest and two previous versions
14330

144-
Use inline Markdown links: [Link text](https://example.com).
31+
## Code validation
14532

146-
Link to other sections using descriptive phrases that include the section name:
147-
"For setup details, refer to the [Lists](#lists) section."
33+
**ESLint:** All JavaScript snippets are validated. Use `<!-- eslint-skip -->` for intentionally incomplete code.
14834

149-
Bold text with two asterisks: **bold**
35+
**md-k6.py:** Snippets are executed in CI for changed files in `docs/sources/k6/next/`. Control with HTML comments:
15036

151-
Emphasize text with one underscore: _italics_
37+
- `<!-- md-k6:skip -->` - Skip snippet
38+
- `<!-- md-k6:skipall -->` - Skip entire file
39+
- `<!-- md-k6:nofail -->` - Allow errors
40+
- `<!-- md-k6:env.VAR=value -->` - Set environment variables
41+
- `<!-- md-k6:arg.--flag=value -->` - Add CLI arguments
42+
- `<!-- md-k6:nothresholds -->` - Disable thresholds
43+
- `<!-- md-k6:fixedscenarios -->` - Don't override scenarios
15244

153-
Format UI elements using sentence case as they appear:
45+
**Run locally:** `python3 scripts/md-k6.py [-d 5s] <path>`
15446

155-
- Click **Submit**.
156-
- Navigate to **User settings**.
157-
- Configure **Alerting rules**.
47+
## Hugo shortcodes
15848

159-
### Lists
49+
Always preserve shortcodes when editing:
16050

161-
Write complete sentences for lists:
51+
- **Admonitions:** `{{< admonition type="note|caution|warning" >}}...{{< /admonition >}}` (use sparingly)
52+
- **Shared content:** `{{< docs/shared lookup="path/to/file.md" source="k6" version="next" >}}`
53+
- **Others:** Refer to [Writers' Toolkit](https://grafana.com/docs/writers-toolkit/write/shortcodes/) for tabs, collapsible sections, etc.
16254

163-
- Works with all languages and frameworks (correct)
164-
- All languages and frameworks (incorrect)
55+
## k6 terminology
16556

166-
Use dashes for unordered lists.
57+
**Product names:** Grafana k6 (first mention) → k6; k6 OSS; Grafana Cloud k6 (always full); k6 Studio
16758

168-
Bold keywords at list start and follow with a colon.
59+
**Core concepts:** VUs (virtual users), Iterations, Scenarios, Thresholds, Checks, Metrics (`http_req_duration`, Counter, Gauge, Rate, Trend), Executors (`shared-iterations`, `constant-vus`, `ramping-vus`), Options, Init context, Default function
16960

170-
### Images
171-
172-
Include descriptive alt text that conveys the essential information or purpose.
173-
174-
Write alt text without "Image of..." or "Picture of..." prefixes.
175-
176-
### Code
177-
178-
Use single code backticks for:
179-
180-
- user input
181-
- placeholders in markdown, for example _`<PLACEHOLDER_NAME>`_
182-
- files and directories, for example `/opt/file.md`
183-
- source code keywords and identifiers,
184-
for example variables, function and class names
185-
- configuration options and values, for example `PORT` and `80`
186-
- status codes, for example `404`
187-
188-
Use triple code backticks followed by the syntax for code blocks, for example:
61+
**API pattern:**
18962

19063
```javascript
191-
console.log("Hello World!");
192-
```
64+
import http from 'k6/http';
65+
import { check, sleep } from 'k6';
19366

194-
Introduce each code block with a short description.
195-
End the introduction with a colon if the code sample follows it, for example:
67+
export const options = { vus: 10, duration: '30s' };
68+
const baseUrl = __ENV.BASE_URL || 'https://test.k6.io';
19669

197-
```markdown
198-
The code sample outputs "Hello World!" to the browser console:
199-
200-
<CODE_BLOCK>
70+
export default function () {
71+
const res = http.get(`${baseUrl}/`);
72+
check(res, { 'is status 200': (r) => r.status === 200 });
73+
sleep(1);
74+
}
20175
```
20276

203-
Use descriptive placeholder names in code samples.
204-
Use uppercase letters with underscores to separate words in placeholders,
205-
for example:
77+
## Local development
20678

207-
```sh
208-
OTEL_RESOURCE_ATTRIBUTES="service.name=<SERVICE_NAME>
209-
OTEL_EXPORTER_OTLP_ENDPOINT=<OTLP_ENDPOINT>
210-
```
79+
**Prerequisites:** Docker/Podman, Node.js ≥16, `npm` ≥7
21180

212-
The placeholder includes the name and the less than and greater than symbols,
213-
for example <PLACEHOLDER_NAME>.
81+
**Build:** `npm start` → <http://localhost:3002/docs/k6/> (auto-rebuilds on changes)
21482

215-
If the placeholder is markdown emphasize it with underscores,
216-
for example _`<PLACEHOLDER_NAME>`_.
83+
**Lint:** `npm install` then `npx eslint "**/*.md"` (or auto-runs on commit via husky)
21784

218-
In code blocks use the placeholder without additional backticks or emphasis,
219-
for example <PLACEHOLDER_NAME>.
85+
## Deployment & releases
22086

221-
Provide an explanation for each placeholder,
222-
typically in the text following the code block or in a configuration section.
87+
**Auto-deploy:** PRs merged to `main` with `docs/sources/` changes sync via `publish-technical-documentation.yml` → <https://grafana.com/docs/k6/>
22388

224-
Follow code samples with an explanation
225-
and configuration options for placeholders, for example:
89+
**New release:** Duplicate `next/` → rename to `v{MAJOR}.{MINOR}.x/`, verify locally, commit. Highest version becomes "latest".
22690

227-
```markdown
228-
<CODE_BLOCK>
91+
## AI agent checklist
22992

230-
This code sets required environment variables
231-
to send OTLP data to an OTLP endpoint.
232-
To configure the code refer to the configuration section.
93+
**All edits:** Check version (next/ vs. current), preserve front matter + shortcodes, use active voice/present tense/second person, validate code
23394

234-
<CONFIGURATION>
235-
```
236-
237-
Put configuration for a code block after the code block.
95+
**Code examples:** Full working scripts, add `<!-- md-k6:skip -->` if incomplete, include imports, explain behavior, use proper syntax
23896

239-
## APIs
97+
**APIs:** Show imports, provide examples, document parameters/returns, link related content
24098

241-
When documenting API endpoints specify the HTTP method,
242-
for example `GET`, `POST`, `PUT`, `DELETE`.
99+
**Structural changes:** Update both versions, fix navigation + links, use `apply-patch`, test build
243100

244-
Provide the full request path, using backticks.
101+
## Best practices
245102

246-
Use backticks for parameter names and example values.
103+
**Writing:** Assume developer knowledge, focus on practical solutions, explain when/why, include working examples, link related docs
247104

248-
Use placeholders like `{userId}` for path parameters, for example:
105+
**Code quality:** Complete runnable examples, realistic scenarios, idiomatic k6 patterns, explain non-obvious logic, keep concise
249106

250-
- To retrieve user details, make a `GET` request to `/api/v1/users/{userId}`.
107+
**Maintenance:** Sync versions with `apply-patch`, update all references, verify links, monitor CI, review carefully
251108

252-
### CLI commands
109+
## Resources
253110

254-
When presenting CLI commands and their output,
255-
introduce the command with a brief explanation of its purpose.
256-
Clearly distinguish the command from its output.
111+
- [k6 documentation](https://grafana.com/docs/k6/)
112+
- [k6 GitHub repository](https://github.com/grafana/k6)
113+
- [Grafana Writers' Toolkit](https://grafana.com/docs/writers-toolkit/)
114+
- [Contributing guide](./CONTRIBUTING/README.md)
115+
- [Code of conduct](./CODE_OF_CONDUCT.md)
257116

258-
For commands, use `sh` to specify the code block language.
117+
---
259118

260-
For output, use a generic specifier like `text`, `console`,
261-
or `json`/`yaml` if the output is structured.
262-
263-
For example:
119+
<!-- docs-ai-begin -->
120+
<!-- version: 1.2.0 -->
264121

265-
```markdown
266-
To list all running pods in the `default` namespace, use the following command:
122+
## Style guide (AI toolkit)
267123

268-
<CODE_BLOCK>
269-
```
124+
**Role:** Technical writer for Grafana Labs. Audience: developers who understand programming.
270125

271-
The output will resemble the following:
126+
**Base:** Follow [Google Developer Documentation Style Guide](https://developers.google.com/style) - active voice, second person, present tense, conversational tone, sentence case.
272127

273-
```text
274-
NAME READY STATUS RESTARTS AGE
275-
my-app-deployment-7fdb6c5f65-abcde 1/1 Running 0 2d1h
276-
another-service-pod-xyz123 2/2 Running 0 5h30m
277-
```
128+
**Product naming:** Full name first (Grafana Alloy), then short (Alloy). Always "Grafana Cloud" (full). No abbreviations: "OpenTelemetry" not "OTel", "Kubernetes" not "K8s".
278129

279-
### Shortcodes
130+
**Structure:** Front matter YAML `title` = h1 heading. Add intro after headings. Start with goal + prerequisites. End with next steps/related resources.
280131

281-
Leave Hugo shortcodes in the content when editing.
132+
**Writing:** Simple words (use/help/show not utilize/assist/demonstrate). Verbs + nouns. Complete sentences in lists. allowlist/blocklist, primary/secondary. "refer to" not "see".
282133

283-
Use our custom admonition Hugo shortcode for notes, cautions, or warnings,
284-
with `<TYPE>` as "note", "caution", or "warning":
134+
**Formatting:** Inline links `[text](url)`. Bold `**text**`. Italics `_text_`. Backticks for: user input, files, code identifiers, configuration options, status codes. Placeholders: _`<UPPERCASE_WITH_UNDERSCORES>`_ in prose, `<UPPERCASE>` in code blocks.
285135

286-
```markdown
287-
{{< admonition type="<TYPE>" >}}
288-
...
289-
{{< /admonition >}}
290-
```
136+
**Code blocks:** Introduce with colon, use language identifier (`javascript`, `sh`), explain placeholders after. For CLI: `sh` for commands, `text`/`json`/`yaml` for output.
291137

292-
Use admonitions sparingly.
293-
Only include exceptional information in admonitions.
138+
**APIs:** Specify HTTP method (`GET`), full path in backticks, placeholders like `{userId}`.
294139

295140
<!-- docs-ai-end -->

0 commit comments

Comments
 (0)