diff --git a/.ai/AI-README.md b/.ai/AI-README.md index 2243ccfcdec6b..6edd2220824be 100644 --- a/.ai/AI-README.md +++ b/.ai/AI-README.md @@ -22,6 +22,7 @@ Use `resources/terms.md` when terminology is uncertain or not covered by the qui - `.ai/skills/review-doc-pr/`: review documentation PRs and Markdown diffs for factual accuracy, user usefulness, completeness, version fit, related-doc impact, links, and style - `.ai/skills/create-or-update-zh-translation-pr/`: create a new docs translation PR or update an existing one by combining repo-local scripts with minimal-edit translation rules and incremental source-diff handling +- `.ai/skills/writing-doc-summaries/`: write or update the `summary` front matter field in a document following the repo's 115-145 character SEO-friendly sentence rules The translation skill includes bundled scripts under `.ai/skills/create-or-update-zh-translation-pr/scripts/` for: diff --git a/.ai/skills/writing-doc-summaries/SKILL.md b/.ai/skills/writing-doc-summaries/SKILL.md new file mode 100644 index 0000000000000..72f4b14249ea1 --- /dev/null +++ b/.ai/skills/writing-doc-summaries/SKILL.md @@ -0,0 +1,142 @@ +--- +name: writing-doc-summaries +description: Writes or updates the front matter `summary` field in pingcap/docs and pingcap/docs-cn Markdown files. The summary is an SEO-friendly sentence of 115-145 characters. Use when a document is missing a summary, when a reviewer or CI check flags a low-quality summary, or when an existing summary is outdated, inaccurate, or the wrong length. +--- + +# Writing Doc Summaries + +Write or improve the `summary` field in the YAML front matter of Markdown files in `pingcap/docs` and `pingcap/docs-cn`. + +## Front matter example + +```yaml +--- +title: Back up and Restore Data Using Dumpling and TiDB Lightning +summary: Learn how to use Dumpling and TiDB Lightning to back up and restore full data of TiDB. +--- +``` + +## Summary rules + +1. **Length**: 115-145 characters including spaces. +2. **Opening verb**: Start with an SEO-friendly verb phrase (see table below) that tells the reader what they will get from this document. Never start with the document title, a product name alone, or a noun phrase. +3. **Perspective**: Reader-focused — tell them what they will learn or do. +4. **No special leading characters**: Do not start with `>`, `*`, `#`, `-`, or `[`. +5. **YAML quoting**: Wrap the value in double quotes if it contains `:` or other YAML special characters. +6. **No redundancy**: Do not repeat the document title word-for-word. Rephrase to add value. +7. **Language**: Match the document body language. Chinese body → Chinese summary. +8. **Self-contained**: Must be understandable without the title or body — it may appear as a standalone search snippet. +9. **Accuracy**: Must match the actual scope of the document. Do not promise content the document does not deliver. +10. **Tone**: Conversational but professional. No marketing language. + +## Structure formula + +For most document types, a reliable pattern is: + +**[Action/Topic] + [Object] + [Outcome/Value]** + +| Part | What it covers | Example | +|---|---|---| +| Action/Topic | Opening verb phrase | `Learn how to configure` | +| Object | What the document is about | `TLS encryption between TiDB components` | +| Outcome/Value | What the reader gains or achieves | `to secure data in transit and meet compliance requirements` | + +Full example: `Learn how to configure TLS encryption between TiDB components to secure data in transit and meet compliance requirements.` + +**Exceptions:** + +- **SQL statement reference**: Use fixed template — `An overview of the usage of for the TiDB database`. No outcome clause needed. +- **Focused task docs**: Omit the outcome clause if the action and object already imply it and the sentence meets minimum length. + +## Opening verb guidance + +Scan a few existing summaries in the same subdirectory first to match local conventions. + +### Preferred patterns + +| Document type | Preferred opening | +|---|---| +| Concept / overview | Learn what, Learn how X works, Learn about, Introduce the concept of | +| Feature introduction | Introduce, Introduce the, Learn about | +| Task / procedure | Learn how to | +| Quick start | Learn how to quickly get started with | +| Configuration | Learn all the configuration options for, Learn how to configure | +| Troubleshooting | Learn how to troubleshoot, Learn how to diagnose | +| SQL statement reference | An overview of the usage of `` for the TiDB database | +| Release notes | Learn about the new features, compatibility changes, improvements, and bug fixes in TiDB `` | + +### Patterns to avoid + +- Starting with the product name alone: `TiDB ...`, `TiKV ...` +- `This document`, `This guide`, `This article`, `This page` +- `Explains`, `Describes` (use `Learn` or `An overview of` instead) +- `The reference for`, `The usage of` +- Repeating the document title word-for-word + +## Before and after + +**Before** (vague, filler opening, no outcome): + +```yaml +summary: This document explains the auto-tune feature of Backup & Restore. +``` + +**After** (reader-focused, specific, includes outcome): + +```yaml +summary: Learn how the BR auto-tune feature automatically limits backup resource usage to reduce impact on online TiDB cluster performance. +``` + +**Before** (generic, no user intent): + +```yaml +summary: An introduction to metadata lock in TiDB. +``` + +**After** (introduces concept and explains why it matters): + +```yaml +summary: Introduce the concept, principles, and implementation of metadata lock in TiDB, and learn how it prevents DDL and DML conflicts. +``` + +## Workflow + +1. **Read** the target Markdown file fully. Note the title, opening paragraph, main sections, scope, and any existing `summary`. + +2. **Draft** 2-3 candidate sentences using the structure formula and the opening-verb table. + +3. **Validate** each candidate: + - Count characters. Must be 115-145. + - Confirm opening verb fits the document type. + - Confirm it does not promise content the document lacks. + - Confirm language matches the document body. + - If it contains `:`, confirm the value is wrapped in double quotes. + +4. **If validation fails** → revise and re-validate. Repeat until all checks pass. + +5. **Apply** the best candidate: + - If front matter exists, update the `summary` line in place. + - If front matter is missing, add it at the top: + + ```yaml + --- + title: + summary: + --- + ``` + + - Preserve all other front matter fields. Do not change the document body. + +6. **Final check**: Re-count characters one more time after editing. Confirm `title` matches the H1. Confirm no special leading character without wrapping quotes. + +## Output expectations + +- Apply the change directly using the Edit tool. +- Report the final summary text and its character count. +- If the existing summary is already acceptable, say so and explain why. +- Prefer a full rewrite over minor edits when the existing summary is structurally weak. +- Do not rewrite or reformat any other part of the document. + +## Gut check + +Before applying: **would this make a TiDB user want to click through from search results?** If not, rewrite.