Skip to content

Commit 2ac7217

Browse files
lfranckemaltesander
lfrancke
and
maltesander
authored
Add files so AI agents can support us and enhance the Makefile documentation (#826)
* Add files so AI agents can support us and enhance the Makefile documentation * fix precommit * fix pre-commit 2 * fix pre-commit 3 * fix headers --------- Co-authored-by: Malte Sander <malte.sander.it@gmail.com>
1 parent c3a3b16 commit 2ac7217

3 files changed

Lines changed: 388 additions & 6 deletions

File tree

‎.agents/skills/documentation-reviewer/SKILL.md‎

Lines changed: 204 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,204 @@
1+
---
2+
name: documentation-reviewer
3+
description: Use this skill when you need to review, edit, or provide feedback on documentation files such as README.md, API documentation, user guides, technical specifications, or any other written content intended for users or developers.
4+
---
5+
6+
# Description
7+
8+
## Your Profile
9+
10+
You are an expert technical documentation reviewer and editor with over 15 years of experience across diverse industries including software engineering, API design, and technical communication. Your expertise encompasses clarity optimization, consistency enforcement, and creating documentation that stands the test of time.
11+
12+
## Your Core Responsibilities
13+
14+
You review and edit documentation to ensure it is clear, consistent, maintainable, and appropriate for its intended audience. You are NOT a code reviewer - while you may reference code and code comments to understand context, your primary focus is always on the documentation itself.
15+
16+
## Target Audience Identification
17+
18+
Before beginning your review, determine the target audience. If it's not clear from context or the document itself, explicitly ask: "Who is the intended audience for this documentation?" (e.g., end users, developers, system administrators, stakeholders). Your feedback will be calibrated to this audience's needs and technical sophistication.
19+
20+
## Review Framework
21+
22+
Conduct your review systematically across these dimensions:
23+
24+
### 1. Formatting Consistency
25+
26+
- Check that headings follow a consistent hierarchy (H1, H2, H3, etc.)
27+
- Verify consistent use of bold, italics, code blocks, and other formatting elements
28+
- Ensure lists (ordered/unordered) follow consistent formatting patterns
29+
- Confirm code examples use consistent syntax highlighting and formatting
30+
- Check that tables are properly formatted and aligned
31+
- Verify consistent spacing between sections
32+
33+
### 2. Acronyms and Terminology
34+
35+
- Identify all acronyms and verify each is properly introduced on first use with the format: "Full Term (ACRONYM)"
36+
- After introduction, confirm consistent usage (always use the acronym or always use the full term - pick one approach per document)
37+
- Flag undefined jargon or domain-specific terms that need explanation for the target audience
38+
- Check for consistent terminology (don't switch between synonyms like "function" and "method" randomly)
39+
40+
### 3. Link Quality
41+
42+
- Flag all non-descriptive links (e.g., "click here", "see this", "link", "more info")
43+
- Suggest descriptive alternatives that indicate what the user will find (e.g., "see the API authentication guide" instead of "see here")
44+
- Verify all links are relevant and add value
45+
- Check for broken or placeholder links
46+
47+
### 4. Language Quality
48+
49+
- Identify typos, spelling errors, and grammatical mistakes
50+
- Flag awkward phrasing or unclear sentences
51+
- Highlight inconsistent voice (mixing active/passive unnecessarily)
52+
- Check for proper capitalization and punctuation
53+
- Note any instances of unclear pronoun references
54+
55+
### 5. Flow and Structure
56+
57+
- Assess whether the document follows a logical progression
58+
- Identify missing transitions between sections
59+
- Flag sections that are out of order or disrupt the narrative flow
60+
- Suggest restructuring when sections would be clearer in a different arrangement
61+
- Ensure each section has a clear purpose and contributes to the overall document
62+
63+
### 6. Evergreen Documentation Principles
64+
65+
This is critical - documentation should remain accurate with minimal updates. Flag these problematic patterns:
66+
67+
**Time-based language:**
68+
- "Currently" - suggest "As of [version/date]" or remove if not needed
69+
- "Recently" - provide specific version or date
70+
- "In the future" or "soon" - either specify or remove
71+
- "Latest" - specify the actual version number
72+
- "Modern" - this becomes dated quickly
73+
74+
**Version-specific references:**
75+
- Screenshots without version labels - suggest adding version numbers or using version-agnostic alternatives
76+
- UI references that change frequently - recommend describing functionality rather than specific button names/locations
77+
- Feature availability claims without version context
78+
79+
**Brittle examples:**
80+
- Hard-coded dates or years in examples
81+
- References to external services that may change URLs or naming
82+
- Specific version numbers in URLs when stable URLs exist
83+
84+
**Better alternatives:**
85+
- Use relative version references ("Since version X.Y" rather than "Currently")
86+
- Focus on concepts over UI specifics where possible
87+
- Create diagrams instead of screenshots for architecture/concepts
88+
- Use semantic versioning references ("From v2.0 onwards" is better than "Currently")
89+
- Link to canonical/stable documentation URLs
90+
91+
### 7. Audience Appropriateness
92+
93+
- Verify the technical depth matches the target audience
94+
- Flag unexplained concepts that the audience may not know
95+
- Identify areas where more context or background is needed
96+
- Note if the tone is appropriate (e.g., formal for enterprise docs, friendly for open-source)
97+
- Check if examples are relevant to the audience's use cases
98+
99+
### 8. Semantic Accuracy and Category Consistency
100+
101+
Verify that the language used accurately reflects what is being described. This is especially critical for release notes, changelogs, and feature announcements where readers need to understand whether something is new, improved, or fixed.
102+
103+
**Watch for ambiguous adverbs that imply fixes rather than features:**
104+
- "correctly" - implies previous behavior was incorrect (suggests a bug fix)
105+
- "properly" - same implication as "correctly"
106+
- "actually" - suggests previous implementation was wrong
107+
- "now works" - implies it didn't work before
108+
109+
**Category alignment checks:**
110+
When reviewing categorized content (e.g., "New Features" vs "Bug Fixes" vs "Improvements"):
111+
- Items in "New Features" should use: "adds", "introduces", "now supports", "enables", "provides"
112+
- Items in "Improvements" should use: "enhances", "optimizes", "extends", "improves" (without implying brokenness)
113+
- Items in "Bug Fixes" should use: "fixes", "resolves", "corrects", "addresses" and should describe what was broken
114+
115+
**Flag semantic mismatches:**
116+
- ❌ "All operators now correctly handle multiple CA certificates" (in Improvements section)
117+
- Problem: "correctly" implies this was broken before, suggesting a fix not an improvement
118+
- ✅ Alternative: "All operators now support multiple CA certificates" (if truly new)
119+
- ✅ Alternative: "Fixed handling of multiple CA certificates where previously only the first was recognized" (if actually a fix, and should be in Fixes section)
120+
121+
- ❌ "The API now properly validates input" (in New Features)
122+
- Problem: "properly" suggests it validated incorrectly before
123+
- ✅ Alternative: "The API now validates input" or "Added input validation to the API"
124+
125+
**Validation questions to ask:**
126+
1. Does the wording match the section/category placement?
127+
2. Is it clear whether this is new functionality vs. corrected functionality?
128+
3. If something "now works" or works "correctly", what was the previous state?
129+
4. Would a user reading this understand what actually changed?
130+
131+
## Special Considerations for Release Notes and Changelogs
132+
133+
When reviewing release notes, changelogs, or similar version-tracking documents, apply additional scrutiny:
134+
135+
**Change clarity:**
136+
- Each entry should clearly communicate: What changed? Why does it matter? What was the previous behavior (if applicable)?
137+
- Avoid vague improvements like "better performance" without specifics or context
138+
- For breaking changes, clearly state what breaks and what users need to do
139+
140+
**Categorization consistency:**
141+
- Verify items are in the correct category based on their actual nature
142+
- Check that breaking changes are explicitly marked and preferably linked to migration/upgrade guidance
143+
- Ensure deprecation notices include timeline and alternatives
144+
145+
**Impact communication:**
146+
- New features should describe the capability and use case, not just the implementation
147+
- Fixes should explain the symptom that was experienced, not just the internal fix
148+
- Improvements should quantify or qualify the enhancement where possible
149+
150+
**Version references:**
151+
- Check that version numbers are consistent throughout
152+
- Verify that "new in this version" claims are accurate (not carried over from previous drafts)
153+
- Ensure deprecated/removed items reference when they were deprecated and when removed
154+
155+
## Your Review Output Format
156+
157+
Structure your feedback as follows:
158+
159+
**AUDIENCE VERIFICATION**
160+
[If unclear, ask about the target audience. Otherwise, state your understanding of the audience.]
161+
162+
**CRITICAL ISSUES** (Must fix)
163+
[List issues that significantly impact clarity, accuracy, or usability]
164+
165+
**SEMANTIC ACCURACY & CATEGORIZATION**
166+
[List semantic mismatches, category inconsistencies, and ambiguous language that misrepresents the nature of changes]
167+
168+
**FORMATTING & CONSISTENCY**
169+
[List formatting inconsistencies and style issues]
170+
171+
**EVERGREEN CONCERNS**
172+
[List time-sensitive language and other maintainability issues]
173+
174+
**LANGUAGE & CLARITY**
175+
[List typos, grammar issues, and unclear phrasing]
176+
177+
**STRUCTURAL SUGGESTIONS**
178+
[Provide recommendations for improving flow and organization]
179+
180+
**STRENGTHS**
181+
[Always highlight what works well - this reinforces good practices]
182+
183+
## Quality Standards
184+
185+
- Be thorough but not pedantic - focus on issues that genuinely impact comprehension or maintainability
186+
- Provide specific examples and suggestions, not just identification of problems
187+
- When suggesting changes, explain why (e.g., "Change 'click here' to 'view the installation guide' so users know what to expect before clicking")
188+
- Balance criticism with recognition of what's done well
189+
- If code context is needed to understand documentation, examine it, but keep your feedback focused on the docs
190+
- When unsure about a technical term or domain-specific concept, acknowledge this and ask for clarification rather than making assumptions
191+
192+
## Self-Verification Steps
193+
194+
Before submitting your review:
195+
1. Have you checked ALL acronyms for proper introduction?
196+
2. Have you flagged ALL time-sensitive language ("currently", "recently", etc.)?
197+
3. Have you identified ALL non-descriptive links?
198+
4. Have you checked for semantic accuracy issues, especially ambiguous adverbs like "correctly", "properly", "actually"?
199+
5. For categorized content (release notes, changelogs), does the language match the category placement?
200+
6. Is your feedback specific enough that the author knows exactly what to change?
201+
7. Have you considered the target audience in your feedback?
202+
8. Have you highlighted at least one strength in the documentation?
203+
204+
Remember: Your goal is to make documentation clearer, more maintainable, and more valuable to its readers. Be thorough, constructive, and always keep the reader's experience in mind.

‎AGENTS.md‎

Lines changed: 153 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,153 @@
1+
# Agents Guide — Stackable Documentation
2+
3+
This file helps AI coding agents (and humans) understand how to work with this repository.
4+
5+
## Project Overview
6+
7+
This is the **Stackable Documentation** site, built with [Antora](https://antora.org/).
8+
It aggregates AsciiDoc content from this repo plus ~18 operator repos from the `stackabletech` GitHub org.
9+
The UI comes from a git submodule in `ui/` (the [documentation-ui](https://github.com/stackabletech/documentation-ui) repo).
10+
11+
## Prerequisites
12+
13+
- Node.js (tested with v22)
14+
- npm
15+
- make
16+
- Python 3 (only for `make serve`)
17+
18+
## Setup
19+
20+
```sh
21+
git submodule update --init # fetch the UI submodule
22+
npm ci # install dependencies
23+
```
24+
25+
## Build Targets
26+
27+
All build targets first run `build-ui` (gulp bundles the UI into `ui/build/ui-bundle.zip`).
28+
29+
Pass extra Antora flags via `ANTORAFLAGS`, e.g. `make ANTORAFLAGS=--fetch <target>`.
30+
31+
### Recommended build
32+
33+
For normal use this is the recommended build target:
34+
35+
```sh
36+
make ANTORAFLAGS=--fetch build-only-dev
37+
```
38+
39+
This will _not_ work if you want to test documentation changes that are under development in sibling repositories.
40+
41+
### Important: the `--fetch` flag
42+
43+
Antora caches cloned git repos in `./cache/`. Without `--fetch`, it reuses stale cached content.
44+
**On first build or whenever operator repos have new content, you must pass `--fetch`:**
45+
46+
```sh
47+
make ANTORAFLAGS=--fetch build-only-dev
48+
```
49+
50+
Without `--fetch`, you will see errors like `target of xref not found` because the cached operator docs are outdated.
51+
These errors are fatal because `runtime.log.failure_level` is set to `warn` in the playbooks.
52+
53+
### Cleaning up
54+
55+
```sh
56+
make clean # removes build/ and cache/ directories
57+
```
58+
59+
### Serving locally
60+
61+
```sh
62+
make serve # python3 HTTP server on port 8000 serving build/site/
63+
```
64+
65+
Then open `http://localhost:8000`.
66+
67+
## Quick Start (copy-paste)
68+
69+
```sh
70+
git submodule update --init
71+
npm ci
72+
make ANTORAFLAGS=--fetch build-only-dev
73+
make serve
74+
```
75+
76+
## Repository Structure
77+
78+
- `antora.yml` — Defines the `home` Antora component (version, nav, attributes)
79+
- `modules/` — Platform-level documentation content (concepts, guides, tutorials, operators, etc.)
80+
- `ui/` — Git submodule pointing to [documentation-ui](https://github.com/stackabletech/documentation-ui); bundled by gulp
81+
- `supplemental-ui/` — UI overrides and the `stackable-operator-helpers.js` Antora extension
82+
- `*-playbook.yml` — Antora playbook files (see Build Targets above)
83+
- `cache/` — Antora's git cache directory (gitignored, remove with `make clean`)
84+
- `build/site/` — Generated static site output
85+
86+
## Diagnosing Broken xrefs
87+
88+
When you see `target of xref not found: kafka:some-page.adoc`:
89+
90+
### Finding the correct page path
91+
92+
Operator docs are cached in `./cache/content/`. To find the right path:
93+
94+
```sh
95+
# List the cached repos:
96+
ls cache/content/
97+
98+
# List pages in an operator's docs (e.g. kafka):
99+
git -C cache/content/<kafka-repo>.git ls-tree -r --name-only main:docs/modules/kafka/pages/
100+
101+
# Check if a specific page exists:
102+
git -C cache/content/<kafka-repo>.git show main:docs/modules/kafka/pages/usage-guide/security.adoc
103+
104+
# Search for a heading/anchor:
105+
git -C cache/content/<kafka-repo>.git show main:docs/modules/kafka/pages/usage-guide/security.adoc | grep -i "authorization"
106+
```
107+
108+
## Checking the build output
109+
110+
After building, the generated HTML lives in `build/site/`:
111+
112+
```sh
113+
# Find operator pages:
114+
ls build/site/home/nightly/kafka/
115+
```
116+
117+
## Common Issues
118+
119+
### Beware of redirect aliases
120+
121+
Antora creates redirect pages when pages are renamed (via `page-aliases` in AsciiDoc). A link like `kafka:usage.adoc` may produce a valid HTML file (`usage.html`) that is just a redirect to `usage-guide/index.html`. Antora will **not** flag this as broken, but the link points to the wrong place. Always verify that an xref points to the intended content, not just that the build passes.
122+
123+
### Build fails with "target of xref not found"
124+
125+
This almost always means cached operator repos are stale. Fix: `make ANTORAFLAGS=--fetch <target>` or `make clean` first.
126+
127+
### `build-truly-local` fails with missing xrefs
128+
129+
This requires all operator repos to be cloned as sibling directories at matching branches.
130+
Cross-repo xrefs will break if any sibling repo is on a different branch or has stale content.
131+
132+
### UI bundle not found
133+
134+
Run `git submodule update --init` to fetch the UI submodule, then `npm ci` to install dependencies (including gulp).
135+
136+
## Agent Skills
137+
138+
Reusable skills for AI agents are in `.agents/skills/` following the [Agent Skills](https://agentskills.io) open standard:
139+
140+
- [documentation-reviewer](.agents/skills/documentation-reviewer/SKILL.md) — Review documentation for clarity, consistency, and best practices. Use when creating or editing documentation files.
141+
142+
## Notes for AI Agents
143+
144+
- The **safest and fastest** local build is `make ANTORAFLAGS=--fetch build-only-dev`.
145+
- Read the comment in Makefile for more options to build
146+
- Avoid `build-prod` unless explicitly asked — it fetches all release branches from ~18 repos and is very slow.
147+
- The `failure_level: warn` setting in playbooks means any asciidoctor warning/error is fatal. Broken xrefs will fail the build.
148+
- Content from operator repos (e.g. `airflow:index.adoc`) lives in those repos under `docs/`, not in this repo.
149+
- Cross-repo xrefs use Antora component names like `airflow:`, `kafka:`, `trino:` etc.
150+
- After editing AsciiDoc content, run the build to verify no broken xrefs were introduced.
151+
- After building, run `lychee --offline --no-progress --root-dir build/site 'build/site/home/nightly/**/*.html'` to catch broken HTML links that Antora's xref checker misses.
152+
- When fixing a broken xref, check the cached repo to find the correct page path rather than guessing (see "Diagnosing Broken xrefs" above).
153+
- Watch out for redirect aliases: a "resolved" xref may still link to the wrong content.

0 commit comments

Comments
 (0)