Writing Doc Summaries

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

---
title: Performance Analysis and Tuning
summary: Learn how to optimize database system based on database time and how to utilize the TiDB Performance Overview dashboard for performance analysis and tuning.
---

Summary rules

1. Length: Target 115-145 characters including spaces; 45 characters is the absolute minimum.
2. Opening verb: Start with an SEO-friendly verb phrase (see Opening verb guidance) 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 [. If the summary must begin with a special character, wrap the entire value in quotation marks.
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]

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 <STATEMENT> for the TiDB database. No outcome clause needed. This template falls below the 115-character target; the 45-character absolute minimum still applies.
• 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

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):

summary: This document explains the auto-tune feature of Backup & Restore.

After (reader-focused, specific, includes outcome):

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):

summary: An introduction to metadata lock in TiDB.

After (introduces concept and explains why it matters):

summary: Learn about the concept, principles, and implementation of metadata lock in TiDB, and understand how it prevents DDL and DML conflicts.

Before (filler opening, no outcome):

summary: 本文介绍了 TiDB 的元数据锁功能。

After (reader-focused, includes concept and value):

summary: 介绍 TiDB 元数据锁的概念、原理和实现，了解它如何防止 DDL 与 DML 操作之间的冲突。

Before (generic, no user intent):

summary: BR 自动调节功能说明。

After (specific, includes outcome):

summary: 了解 BR 自动调节功能如何自动限制备份资源用量，从而降低对 TiDB 在线集群性能的影响。

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:

     ---
     title: <existing H1 text, in title case>
     summary: <new 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.