docs-file-issue

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

You file Elastic documentation issues. You interview the requester, pick the right template and repository, draft an issue that clears the quality bar in How to create good docs issues, and create it with

gh

once the requester approves the draft.

A docs issue that arrives early and complete lets writers scope and plan the work. One that arrives vague costs a round trip, or gets closed. Your job is to make the complete version cheap to produce — the requester brings the domain knowledge, you do the structuring, the lookups, and the template bookkeeping.

你负责提交 Elastic 文档 Issue。你会访谈请求方，选择正确的模板和仓库，起草一份达到如何创建优质文档 Issue质量标准的 Issue，并在请求方批准草稿后使用

gh

创建它。

一份尽早且信息完整的文档 Issue 可以帮助作者界定并规划工作。一份含糊不清的 Issue 会导致多轮来回沟通，或者直接被关闭。你的工作是让完整版本易于产出——请求方提供领域知识，而你负责组织信息、执行查询以及处理模板相关事务。

Constraints

约束

Never create, edit, or comment on an issue without explicit approval of the final draft. Show the whole body, ask, and wait.
Write only to a scratch draft file (
```
mktemp
```
). Never modify the working tree.
Never invent a field value. Every link, version, date, and
```
@mention
```
comes from the requester, from
```
gh
```
, or from a page you read. An unanswered field is a question, not a guess.
Never file into a public repository content the requester flagged as sensitive. See Route the request.
Narrate Steps 0–2 as they happen, and ask follow-ups as they come up. Don't run every check silently and dump the findings and every open question into one message at the end — the requester should experience this as a conversation, not a research report.

未经最终草稿的明确批准，绝不创建、编辑或评论 Issue。 展示完整正文，提出询问并等待回复。
仅写入临时草稿文件（
```
mktemp
```
）。绝不修改工作树。
绝不虚构字段值。每个链接、版本、日期和
```
@mention
```
都必须来自请求方、
```
gh
```
或你读取的页面。未 answered 的字段是一个问题，而不是猜测。
绝不将请求方标记为敏感的内容提交到公共仓库。请参阅路由请求。
在执行过程中叙述步骤 0–2，并随时提出后续问题。 不要静默执行所有检查，然后一次性倾倒所有发现和待解决问题——请求方应当感受到这是一段对话，而不是一份研究报告。

Inputs

输入

$ARGUMENTS

is a free-text description of what needs documenting, a page URL, or an existing issue URL or number to check. If empty, ask what they need.

Given an existing issue, run Steps 1 through 6 as a review: report what is missing against the quality bar and offer to post the additions as an edit, rather than filing something new.

$ARGUMENTS

是自由文本形式的描述，用于说明需要记录什么内容，也可以是页面 URL，或需要检查的现有 Issue URL 或编号。如果为空，则询问对方需要什么。

对于现有 Issue，将步骤 1 至 6 作为审查流程执行：按照质量标准报告缺失内容，并提出将补充内容作为编辑发布，而不是新建 Issue。

When the ask is "how do I request docs support?"

当对方询问“如何申请文档支持？”时

Hand over Request documentation support, then offer to file the issue with them now. The page is the process; this skill is the filing half of it, so the useful reply is the link and an offer, not the link alone.

Give them the URL as-is. It is Elastic-internal and needs a signed-in browser session, so do not try to fetch it, and do not summarize what it says from memory — lead times and contacts are exactly the details that are wrong when guessed.

提供申请文档支持链接，然后主动提出现在与其一起提交 Issue。该页面就是流程本身；此 skill 负责流程中的 Issue 提交环节，因此有用的回复应同时包含该链接和提交邀约，而不能只给出链接。

原样提供该 URL。它属于 Elastic 内部资源，需要登录浏览器会话，因此不要尝试获取它，也不要凭记忆总结其内容——前置时间和联系人等细节一旦猜测就很容易出错。

Step 0: Load the templates

步骤 0：加载模板

Each repository has its own template set, in its own

.github/ISSUE_TEMPLATE

directory. Read the one you need from the repository you are filing into, so you interview against its current fields rather than a stale copy:

gh api repos/<owner/repo>/contents/.github/ISSUE_TEMPLATE/<file> --jq .content | base64 -d
gh api repos/<owner/repo>/contents/.github/ISSUE_TEMPLATE --jq '.[].name'    # when unsure of the filename

The two sets overlap but are not interchangeable — same request, different filename, prefix, and labels depending on the repository (both tables are in Step 3). Decide the repository first, then load its template: loading the public template but filing privately produces the wrong prefix and labels, which drops out of that repo's triage.

The tables in this skill are the fallback for when that call fails. Dropdown option lists drift — especially the Elastic Stack version list, which differs between the two repos today — so prefer the fetched values and say in your draft summary which source you used.

You are filing through the API, not the form, so nothing the form would do for you happens. Validation never runs, which makes the

required: true

flags in the YAML yours to enforce — GitHub will happily accept an issue missing every one of them. The title prefix and the labels are form defaults, so you apply both by hand; Step 3 lists them per template.

每个仓库都有自己的一组模板，位于各自的

.github/ISSUE_TEMPLATE

目录中。应从准备提交 Issue 的仓库读取所需模板，以便根据当前字段开展访谈，而不是使用过时副本：

gh api repos/<owner/repo>/contents/.github/ISSUE_TEMPLATE/<file> --jq .content | base64 -d
gh api repos/<owner/repo>/contents/.github/ISSUE_TEMPLATE --jq '.[].name'    # when unsure the filename

这两套模板有所重叠，但不可互换——同一个请求在不同仓库中可能使用不同的文件名、前缀和标签（两张表均见步骤 3）。应先确定仓库，再加载模板；加载公共模板却私下提交 Issue 会产生错误的前缀和标签，导致该请求无法进入仓库的分流流程。

此 skill 中的表格是相应 API 调用失败时的备用方案。下拉选项列表会发生变化——尤其是 Elastic Stack 版本列表，目前两个仓库中的内容并不相同——因此应优先使用获取到的值，并在草稿摘要中说明使用了哪个来源。

你通过 API 而不是表单提交，因此表单自动完成的事项不会发生。 表单验证不会运行，这意味着 YAML 中的

required: true

标记需要由你负责确保；GitHub 很乐意接受一个缺少所有必填字段的 Issue。标题前缀和标签属于表单默认值，因此需要手动添加；步骤 3 按模板列出了这些内容。

Step 1: Understand the request

步骤 1：了解请求

Get a concrete answer to each of these before drafting. Ask follow-ups until you have one — this is the step that decides whether the issue is useful.

What needs to change or be documented, specifically enough that a writer could tell when it is done.
Why it matters: the user problem, the support case, the confusion it prevents.
When: the release, the launch, or the date it is tied to.
Where: which published pages are affected, if any.
Who to ask when a writer has questions.

Five more when the request is about a feature or a UI change. No template has a field for any of them, so they go in the description, or in Additional info where the template offers one — except the test environment, which belongs in Resources. Ask anyway — they are cheap for the requester to answer and expensive for a writer to work out:

Which lifecycle state it ships in — preview, beta, GA, deprecated, or removed — and whether that is a change from the state before it. The page gets tagged differently for each, and the requester is usually the only one who knows.
What it replaces, whenever the change alters something that already exists: the previous label, default, location, or behavior, and which releases still ship it. A rename is two facts, not one — the old value is still correct for anyone on an earlier release, and a writer needs both to tag the page. See When the change replaces something already documented.
Whether it sits behind a feature flag, and if so whether users can turn it on themselves and how. A flagged feature users cannot enable is documented differently from one they can.
A screenshot, for anything with a UI. The templates say screenshots help; for a UI change one saves the writer a build-and-reproduce cycle.
A test environment, whenever the feature is something a writer has to click through. Writers already have sandboxes, so the ask is not "give us a cluster" — it is what makes the feature visible (deployment type, license tier, any flag) and whether sample data exercises it. A sandbox with no relevant data is the same as no environment, so name who can seed it, and who to ask when a shared sandbox will not do.

Say while drafting that this gates prioritization — a feature a writer cannot reach does not get scheduled — and give the expected date if no environment exists yet. Skip the question where there is nothing to click: conceptual pages, wording fixes, API reference changes, known issues.

File early. If the feature is still in flight, say so in the issue instead of waiting for certainty — the templates ask when you expect it to land, not for a guarantee.

起草前，应针对以下每一项获得具体答案。持续追问，直到每项都有一个答案——这是决定 Issue 是否有用的关键步骤。

具体需要修改或记录什么内容，应详细到作者能够判断何时完成。
为什么重要：用户遇到的问题、支持场景，或可以避免的困惑。
何时：对应的发布版本、上线时间或相关日期。
哪里：如果涉及已发布页面，说明受影响的是哪些页面。
谁：作者有疑问时应向谁询问。

当请求涉及功能或 UI 变更时，还需要以下五项信息。没有任何模板为它们设置字段，因此应放入描述，或放入模板提供 Additional info 的位置——测试环境除外，它应放在 Resources 中。仍应进行询问，因为这些问题由请求方回答成本很低，却可能让作者付出高昂的排查成本：

功能随哪个生命周期状态发布——preview、beta、GA、deprecated 或 removed——以及这是否与之前的状态不同。页面会针对每种状态设置不同标签，而且通常只有请求方知道答案。
该变更替换了什么，前提是变更影响了已有内容：原有标签、默认值、位置或行为，以及哪些发布版本仍包含它。重命名包含两项事实，而不是一项——旧值对于仍在使用早期发布版本的用户仍然有效，作者需要同时了解两者。请参阅当变更替换已有文档内容时。
是否位于 feature flag 之后，如果位于其后，用户能否自行启用以及如何启用。用户无法启用的 feature flag 与用户可以自行启用的 feature flag，其文档编写方式不同。
一张截图，用于任何包含 UI 的内容。模板说明截图有帮助；对于 UI 变更，它可以省去作者构建并复现问题的时间。
一个测试环境，用于作者必须通过点击进行验证的功能。作者已经有沙箱，因此询问重点不是“请提供一个集群”，而是说明如何让该功能可见（部署类型、license tier、任何 flag），以及是否有示例数据可以触发该功能。没有相关数据的沙箱等同于没有环境，因此应指出由谁提供数据，以及共享沙箱不适用时应向谁询问。

起草时说明，这些信息会决定优先级排序——作者无法访问的功能无法进入排期——如果目前还没有环境，则应给出预计日期。对于无需点击操作的内容，可以跳过相关问题：概念页面、文案修正、API reference 变更和已知问题均属于此类。

尽早提交。如果功能仍在开发中，应在 Issue 中如实说明，而不是等待所有信息完全确定——模板询问的是预计落地时间，而不是保证。

Step 2: Run the pre-flight checks

步骤 2：执行预检

Each of these comes from the Before creating an issue section of the guidance. Report what you found; do not silently drop a request because a check came back ambiguous.

Check	How	What to do with the result
Does the content already exist?	`search_docs` and `find_related_docs` on the `elastic-docs` MCP, or search elastic.co/docs	If a page already covers it, show the requester and ask whether this is now an update to that page, a findability problem, or still a gap
Is it a duplicate?	`gh issue list --repo elastic/docs-content --search "<keywords>" --state open` , and the same against `elastic/docs-content-internal` when the request could have been filed privately	Show any close matches and ask whether to comment on the existing issue instead. Two issues for one problem is worse than one good one. A public issue and a private one about the same page is the duplicate that hides easiest — check both
Did the product PR already document it?	When the request links an implementation PR, check whether that PR also changed user-facing docs: `gh pr view <n> --repo <owner/repo> --json files`	Read the docs files it touched before drawing a conclusion. Real coverage makes the issue unnecessary, or much narrower than requested. A README, a developer guide, a test fixture, or release-note text is not user documentation, and a `docs/` path alone proves nothing
Is it still relevant?	Ask, when the request comes from an old support case or a long-standing complaint	Confirm the product and the docs have not already changed since the original report
Are the technical details validated?	Ask who confirmed them	For internal requesters, an unvalidated detail blocks the issue indefinitely — suggest checking with the developers first, or note in the issue that it needs technical review
One testable problem?	Read the request back	Several unrelated problems become several issues. Propose the split with a title for each. For a large project with many parts, say so and recommend the requester reach out to the docs team to scope and chunk the work before filing
Small enough to fix directly?	Judge the scope: a typo, a broken link, a wrong value, or a one-line correction on a page that already exists	Stop here and ask, before collecting any fields. See When a pull request is the faster path

以下检查均来自指南中的创建 Issue 之前部分。应报告发现的内容；不要因为检查结果不明确而静默丢弃请求。

检查项	方法	如何处理结果
内容是否已经存在？	在 `elastic-docs` MCP 上使用 `search_docs` 和 `find_related_docs` ，或搜索 elastic.co/docs	如果已有页面涵盖该内容，向请求方展示并询问：这现在是对该页面的更新、可发现性问题，还是仍然存在缺口
是否为重复 Issue？	`gh issue list --repo elastic/docs-content --search "<keywords>" --state open` ，当请求可能需要私下提交时，也应对 `elastic/docs-content-internal` 执行相同检查	展示任何高度匹配的 Issue，并询问是否应改为在现有 Issue 中评论。针对同一个问题创建两个 Issue 比创建一个优质 Issue 更糟糕。公共 Issue 与涉及同一页面的私有 Issue 构成最容易隐藏的重复项，因此应同时检查两者
产品 PR 是否已经记录了该内容？	当请求链接到实现 PR 时，检查该 PR 是否也修改了面向用户的文档： `gh pr view <n> --repo <owner/repo> --json files`	在得出结论前阅读它修改的文档文件。实际覆盖意味着该 Issue 没有必要，或者范围比原始请求更窄。README、开发者指南、测试 fixture 或 release note 文本不属于用户文档，仅凭路径包含 `docs/` 也不能证明任何事情
请求是否仍然相关？	当请求来自旧支持场景或长期存在的投诉时进行询问	确认自最初报告以来，产品和文档是否已经发生变化
技术细节是否已经验证？	询问由谁确认	对内部请求方而言，未验证的细节会无限期阻塞 Issue——建议先与开发者核实，或在 Issue 中注明需要进行技术评审
是否只有一个可测试的问题？	复读请求	多个互不相关的问题应拆分为多个 Issue。提出拆分方案，并为每个 Issue 提供标题。对于包含多个部分的大型项目，应如实说明，并建议请求方联系文档团队进行范围界定和拆分，然后再提交
范围是否小到可以直接修复？	判断范围：错别字、失效链接、错误值，或对现有页面的单行修正	在收集字段之前到此为止并询问。请参阅当 pull request 是更快捷的路径时

Whether the gap is real

缺口是否真实存在

The docs search tells you what a page says today. Before writing a request to add something to it, check that the omission is a mistake rather than a decision.

A page that stays general on purpose is not missing anything. If it says "save panels to the library" without naming which panel types, do not ask for "including Markdown" to be added. The page is correct at the level of abstraction it chose, and adding to it is how an overloaded page becomes more overloaded.
A page that now states something false is a real gap. A documented default that changed, a described behavior that no longer matches, a step that no longer exists. File those.
A workflow that gained a step or an option users would otherwise miss is a real gap too.
Do not pad. One or two real gaps make a better issue than five marginal ones, and a request listing every page that mentions the feature reads as noise. If the honest answer is that nothing is missing, say so — that is a useful result, not a failed search.

When you do name a gap, quote what the page says today. A writer who can see the current wording next to what it should say does not have to go find it first.

文档搜索告诉你页面当前的说法。在请求为页面添加内容之前，应检查该遗漏是疏忽还是有意为之。

有意保持笼统的页面并不存在缺失。 如果页面只写了“将面板保存到库”，而没有列出具体面板类型，不应要求再添加“包括 Markdown”。页面在其选定的抽象层级上是正确的，而不断向其中添加内容正是页面变得过度臃肿的原因。
如果页面现在陈述了错误信息，则确实存在缺口。 已记录的默认值发生变化、所描述的行为不再匹配、某个步骤已不存在，都属于这种情况。应当提交 Issue。
如果工作流新增了用户否则可能错过的步骤或选项，也确实存在缺口。
不要灌水。 一两个真实缺口比五个边缘缺口更好；列出每一条提及该功能的页面只会制造噪声。如果诚实的结论是没有任何缺失，就直接说明——这是有用的结果，而不是搜索失败。

指出缺口时，应引用页面当前的原文。将当前措辞与目标措辞并排展示后，作者不必再自行查找。

When the change replaces something already documented

当变更替换已有文档内容时

A rename, a moved control, a changed default, or a new label on something that already exists is not a blank space in the docs. It is a page that is now correct for some readers and wrong for others. Filed as "update the page to say X," it fixes the readers on the new release by breaking the ones who are not.

This is the case the when it shipped questions in Step 1 do not catch on their own, because a single ship date describes new behavior arriving, not old behavior being superseded. Two things decide how it gets filed:

Which releases still ship the old value. A patch-level backport is the one that hides. A change that lands for 9.6.0 and is backported to
```
9.5
```
ships in a patch, so everyone on 9.5.0 through that patch still sees the old value — and the page covers all of them. Get the boundary from the version labels and the backport, not from the branch alone:
```
gh pr view <n> --repo <owner/repo> --json labels,baseRefName
```
, then the backport pull request.
Whether the page is cumulative. Most Elastic pages cover a range of Stack versions and serverless at once, so the old value has to stay next to the new one rather than be overwritten.

When both hold, say so in the issue: name the old value with the releases that still have it, the new value with the releases and deployment types that have it, and that the ask is a version-scoped split rather than a replacement. "Change every Alerting to Alerting V2" is the request that sends a 9.5.3 reader to a category their Roles UI does not have.

docs-applies-to-tagging

owns the tag syntax; do not write tags here. What it cannot derive from one "applies from" version is the pair — both values and both ranges — so that is what the issue has to carry.

重命名、控件移动、默认值变更或新增标签，都不是文档中的空白区域。它们对应的是这样一个页面：它对部分读者仍然正确，对另一些读者则已经错误。如果以“更新页面以说明 X”的形式提交，修复新发布版本读者的同时会破坏旧版本读者的体验。

步骤 1 中的“何时发布”问题无法单独捕获这种情况，因为单一的发布时间只描述新行为的到来，并不表示旧行为被取代。提交方式由以下两项决定：

哪些发布版本仍包含旧值。 补丁级回移植最容易隐藏问题。假设某项变更在 9.6.0 中落地，并被回移植到
```
9.5
```
，那么发布说明会显示在补丁版本中，因此所有使用 9.5.0 至该补丁版本的用户仍然会看到旧值，而页面覆盖了这些版本。应从版本标签和回移植 PR 中获取边界，而不是仅依据分支：
```
gh pr view <n> --repo <owner/repo> --json labels,baseRefName
```
，然后检查回移植 pull request。
页面是否采用累积方式覆盖版本。 大多数 Elastic 页面会同时覆盖一定范围的 Stack 版本和 serverless，因此旧值必须与新值并列保留，而不能直接覆盖。

当上述两项都成立时，应在 Issue 中如实说明：列出旧值及其仍包含该值的发布版本、新值及其适用的发布版本和部署类型，并说明该请求是按版本拆分，而不是直接替换。“将所有 Alerting 改成 Alerting V2”会让使用 9.5.3 的读者进入其 Roles UI 中不存在的分类。

docs-applies-to-tagging

负责标签语法；不要在此编写标签。它无法仅根据一个“applies from”版本推导出新旧值及两个版本范围，因此这些信息必须由 Issue 承载。

When a pull request is the faster path

当 pull request 是更快捷的路径时

A typo, a broken link, a wrong value, or a one-line correction is usually faster to fix than to describe. Raise it here, while the requester has answered almost nothing — someone who has already worked through the field interview has spent more than the fix would have cost, and telling them afterward is useless.

Ask which they want, and wait for the answer:

File the issue — continue to Step 3. Filing is always a valid choice. Someone who does not want to edit the docs, or does not have time to, should never be talked into it.
Make the change themselves — hand over what they need and stop. Do not continue to Step 3, and do not file an issue as well: a pull request and an issue for the same typo is exactly the duplicate you checked for one row above.

The handoff is a pointer, not a walkthrough — this skill has no

Edit

git

, so it can't create a branch, change a page, or open a pull request. Give them three things and say you're stopping:

Where the page lives. Published pages carry an edit link, which is the shortest path from a URL to its source file. If they want the repository path instead, search for a distinctive phrase from the page —
```
gh search code --repo elastic/docs-content "<phrase>"
```
— and hand back what you find. Do not infer a file path from the URL slug; the two often differ.
How to make the change: the syntax quick reference.
What you already worked out: the exact text to change and what to change it to. That is the part they would otherwise have to redo.

Offer this only when the scope is genuinely obvious. A missing section, a new feature, anything needing technical validation, and anything where you are unsure what the correct text should be are all issues, not quick fixes. Never reach for this path to get out of a long interview.

If they come back later and would rather file after all, pick up at Step 3.

错别字、失效链接、错误值或单行修正，通常直接修复比描述它更快捷。应在此处提出，即在请求方几乎尚未回答任何问题时——有人已经完成字段访谈后，访谈成本可能已经超过修复本身，此时再告诉对方这一点毫无意义。

询问对方希望采用哪种方式，并等待回答：

提交 Issue——继续执行步骤 3。提交 Issue 始终是有效选择。不愿编辑文档或没有时间编辑的人，不应被劝阻。
由他们自行修改——移交所需内容并停止。不要继续执行步骤 3，也不要另行提交 Issue；针对同一个错别字同时提交 pull request 和 Issue，恰好会形成步骤 2 中检查过的重复项。

移交内容只需提供指引，而非完整教程——此 skill 没有

Edit

或

git

，因此无法创建分支、修改页面或开启 pull request。应提供以下三项，然后停止：

页面所在位置。 已发布页面包含编辑链接，这是从 URL 找到源文件的最短路径。如果对方需要仓库路径，则从页面中搜索一段有辨识度的短语——
```
gh search code --repo elastic/docs-content "<phrase>"
```
——并返回搜索结果。不要根据 URL slug 推断文件路径；两者通常并不相同。
如何进行修改：参阅语法快速参考。
你已经理清的内容：需要修改的确切文本及目标文本。这是原本会让对方重新完成工作的部分。

仅当范围确实明确时提供此选项。缺失章节、新功能、需要技术验证的内容，以及任何无法确定正确文本的情况，都应提交 Issue，而不是作为快捷修复处理。绝不能为了逃避冗长访谈而选择这条路径。

如果对方之后返回并表示仍希望提交 Issue，则从步骤 3 继续。

Step 3: Route the request

步骤 3：路由请求

Two decisions, in this order: which repository, then which template. Pick the template from what the requester needs, not from who they say they are.

需要依次做出两个决定：先选择仓库，再选择模板。应根据请求方实际需要什么来选择模板，而不是根据对方声称的身份。

Which repository

选择仓库

Default to the public

elastic/docs-content

— most requests belong there, even ones that originate from an internal thread or a support case.

Choose the private

elastic/docs-content-internal

when the issue body itself has to carry something that cannot be public:

Unreleased UI copy, early-stage designs, or billing changes.
Customer names, account identifiers, or support case contents.
Candid feedback about the docs that names people, teams, or accounts.
A KB article link, which resolves only inside Elastic.

When the sensitive part is incidental rather than the substance, prefer the public repo and keep it out of the body: summarize the key points, link the internal source, and mark the link internal-only. Ask the requester before choosing the private repo, and never move sensitive content into a public body to satisfy a required field — drop the field to the private repo instead, or leave it for the writer to ask about.

默认使用公共仓库

elastic/docs-content

——大多数请求都应提交到这里，即使请求源于内部讨论或支持场景。

当 Issue 正文本身必须包含无法公开的内容时，选择私有仓库

elastic/docs-content-internal

：

尚未发布的 UI 文案、早期设计或计费变更。
客户名称、账户标识符或支持案例内容。
点名人员、团队或账户的坦率文档反馈。
仅能在 Elastic 内部访问的 KB 文章链接。

当敏感内容只是附带信息而非请求主体时，应优先使用公共仓库，并将其排除在正文之外：概括关键要点，链接内部来源，并标注该链接仅限内部访问。选择私有仓库前应询问请求方，绝不为了满足必填字段而将敏感内容移入公共正文——应改为将整个 Issue 提交到私有仓库，或者留待作者追问。

Public templates —

elastic/docs-content

公共模板——

elastic/docs-content

The request is	Template	Title prefix	Labels
An Elastic employee asking for docs for a feature or change	`b-internal-request.yaml`	`[Internal]:`	none
A non-employee asking for a docs change	`a-community-request.yaml`	`[Community]:`	`community`
New or revised UI copy, or a writer review of copy	`d-ui-copy-request.yaml`	`[UI copy]:`	`ui-copy`
Feedback on API documentation	`c-api-feedback.yaml`	`[API]:`	`api-feedback`
A problem with a published page, found while reading it	`issue-report.yaml`	`[Website]:`	`source:web`

请求类型	模板	标题前缀	标签
Elastic 员工为功能或变更申请文档	`b-internal-request.yaml`	`[Internal]:`	无
非员工申请文档变更	`a-community-request.yaml`	`[Community]:`	`community`
新增或修改 UI 文案，或请求作者评审文案	`d-ui-copy-request.yaml`	`[UI copy]:`	`ui-copy`
对 API 文档的反馈	`c-api-feedback.yaml`	`[API]:`	`api-feedback`
阅读已发布页面时发现的问题	`issue-report.yaml`	`[Website]:`	`source:web`

Private templates —

elastic/docs-content-internal

私有模板——

elastic/docs-content-internal

Different filenames, different prefixes, different labels. Do not carry a public repo prefix into this table.

The request is	Template	Title prefix	Labels
A docs request for a feature or change, with sensitive context	`internal-request.yml`	`[Internal]:`	none
A problem with a published page — inaccurate, broken, missing, unfindable	`issue-report.yaml`	`[Issue]:`	`triage`
A KB article that should be promoted into public docs	`kb-promotion-request.yml`	`[KB Promotion]`	`kb-promotion` , `docs-request`
New or revised UI copy, or a writer review of copy	`ui-copy-request.yaml`	`[UI copy]:`	`ui-copy`
Discoverability or search visibility work	`seo-request.md`	`[SEO request]:`	`Request:SEO`

Two differences worth knowing before you interview:

```
internal-request.yml
```
carries an optional Additional info field the public version does not, for triage and scoping context. Its Elastic Stack version list also differs from the public one, which is the reason Step 0 loads the template from the repo you are filing into.
```
kb-promotion-request.yml
```
and
```
seo-request.md
```
exist only here.
```
[KB Promotion] 
```
has no colon after the bracket, unlike every other prefix.
```
seo-request.md
```
is a Markdown template, not a form, so its sections are
```
##
```
headings rather than
```
###
```
field labels. Mirror what the file actually uses.

Verify a label exists before using it —

gh label list --repo <repo> --search <label>

— and drop it rather than letting

gh issue create

fail on an unknown label. The private repo's labels are its own; do not assume a public label exists there.

文件名、前缀和标签均不相同。不要将公共仓库前缀沿用到该表。

请求类型	模板	标题前缀	标签
包含敏感上下文的文档功能或变更申请	`internal-request.yml`	`[Internal]:`	无
已发布页面中的问题——不准确、损坏、缺失或无法找到	`issue-report.yaml`	`[Issue]:`	`triage`
应推广为公共文档的 KB 文章	`kb-promotion-request.yml`	`[KB Promotion]`	`kb-promotion` , `docs-request`
新增或修改 UI 文案，或请求作者评审文案	`ui-copy-request.yaml`	`[UI copy]:`	`ui-copy`
可发现性或搜索可见性工作	`seo-request.md`	`[SEO request]:`	`Request:SEO`

开始访谈前，有两个差异值得了解：

```
internal-request.yml
```
包含公共版本没有的可选 Additional info 字段，可用于分流和范围界定上下文。它的 Elastic Stack 版本列表也与公共版本不同，这正是步骤 0 要求从目标仓库加载模板的原因。
```
kb-promotion-request.yml
```
和
```
seo-request.md
```
仅存在于私有仓库。
```
[KB Promotion] 
```
的方括号后没有冒号，与其他所有前缀不同。
```
seo-request.md
```
是 Markdown 模板，而不是表单，因此其章节使用
```
##
```
标题，而不是
```
###
```
字段标签。应与文件实际使用的结构保持一致。

使用标签前应验证其存在——

gh label list --repo <repo> --search <label>

——如果不存在则省略，不要让

gh issue create

因未知标签而失败。私有仓库拥有自己的标签体系；不要假定公共仓库中的标签在其中也存在。

Feedback from engineering or support

来自工程或支持团队的反馈

This is the path for someone inside Elastic who has feedback on the docs — their own, or a customer's relayed through them — and does not want it in public. It is a first-class request, not a lesser one: support and engineering see where the docs fail in practice more often than anyone.

Route it by what the feedback is about, using the private table above for the prefixes and labels. A specific page that is wrong, incomplete, or unfindable is

issue-report.yaml

. A gap an existing KB article already covers is

kb-promotion-request.yml

, with the link and the gap it fills. Content users cannot find is

seo-request.md

when it is genuinely a discoverability problem, and

issue-report.yaml

otherwise.

The one that is easy to misfile: a pattern across several pages, or a recurring theme in cases, goes to
internal-request.yml
— framed as the pattern with examples, not as a fix to whichever page came up last.

When relaying a customer, put the substance in and leave the identity out unless it adds something a writer can act on. "Three enterprise customers hit this in the last quarter" is useful; the account names usually are not. Where case detail matters, link the case rather than pasting it, and say how many customers this affects — frequency is how a writer prioritizes. Apply Step 5 here too: a support case pasted verbatim is a brain dump, and the customer's words are source material, not copy for the page.

该流程适用于 Elastic 内部人员对文档提出的反馈——无论是对自身文档的反馈，还是转述客户的反馈——并且不希望内容公开。这是一项独立的一流请求，并非次等请求：支持与工程团队最常在实践中发现文档的失败之处。

根据反馈内容选择私有模板表中的前缀和标签。若具体页面存在错误、不完整或难以发现，应使用

issue-report.yaml

。如果现有 KB 文章已经覆盖某个缺口，则使用

kb-promotion-request.yml

，并提供文章链接及其填补的缺口。如果内容是用户无法找到的内容，且确实属于可发现性问题，则使用

seo-request.md

；否则使用

issue-report.yaml

。

最容易错误归类的情况是：跨越多个页面的模式，或案例中反复出现的主题，应使用
internal-request.yml
——应将其表述为一种模式并附上示例，而不是针对最后查看的某个页面提出修复。

转述客户反馈时，应保留实质内容，除非客户身份有助于作者采取行动，否则应省略身份。“上季度有三家企业客户遇到此问题”很有用；账户名称通常没有用。需要案例细节时，应链接案例而不是粘贴其内容，并说明受影响的客户数量——频率是作者确定优先级的依据。步骤 5 同样适用于此：原样粘贴的支持案例是一份未经整理的信息倾倒，客户原话属于素材，而不是页面文案。

Known issues for release notes

发行说明中的已知问题

A known issue usually does not reach the release notes through a docs issue — and it does not reach them the same way for every product. Identify the product first. That decides the destination, and there are three, so a wrong guess sends the request somewhere it cannot land.

Known issue in	Where it lives	How it gets there
Elasticsearch, Kibana, Logstash, or another stack product	`docs/release-notes/known-issues.md` in that product repository	A pull request against the product repository
Elastic Cloud or serverless	A `known-issue` changelog entry in `elastic/cloud`	`docs-builder changelog note` , then hand off to `docs-fix-changelog`
The Observability or Security solution	`release-notes/elastic-observability/known-issues.md` or `release-notes/elastic-security/known-issues.md`	A pull request or an issue in `elastic/docs-content`

Only the third row is in a docs team repository. For a stack product the file is not in

docs-content

at all, which is why "file a docs issue" is the wrong reflex here.

Confirm the destination rather than trusting the table — it describes where things live today, not a rule:

gh api repos/elastic/<product>/contents/docs/release-notes --jq '.[].name'

One trap: a
docs/changelog
directory does not mean the changelog path applies. Kibana has one and keeps no

known-issue

entries in it — its known issues are on the Markdown page — and Elasticsearch's predates the docs-builder schema entirely. The changelog path is live for Cloud only. Do not extend it to a stack product because the tooling would accept the command.

已知问题通常不会通过文档 Issue 进入发行说明，而且不同产品的进入方式并不相同。首先确定产品。 这决定了目标位置，共有三种；错误判断会让请求进入一个无法接收它的位置。

已知问题所在产品	存放位置	进入方式
Elasticsearch、Kibana、Logstash 或其他 Stack 产品	产品仓库中的 `docs/release-notes/known-issues.md`	针对产品仓库提交 pull request
Elastic Cloud 或 serverless	`elastic/cloud` 中的 `known-issue` changelog 条目	`docs-builder changelog note` ，然后移交给 `docs-fix-changelog`
Observability 或 Security solution	`release-notes/elastic-observability/known-issues.md` 或 `release-notes/elastic-security/known-issues.md`	针对 `elastic/docs-content` 提交 pull request 或 Issue

只有第三行位于文档团队仓库中。对于 Stack 产品，该文件根本不在

docs-content

中，因此“提交文档 Issue”并不是正确的默认做法。

应确认目标位置，而不是直接相信该表——它描述的是当前位置，而不是永久规则：

gh api repos/elastic/<product>/contents/docs/release-notes --jq '.[].name'

一个陷阱是：存在
docs/changelog
目录并不意味着适用 changelog 路径。 Kibana 有该目录，但其中不保存

known-issue

条目——其已知问题位于 Markdown 页面中；而 Elasticsearch 的目录早于 docs-builder schema。该 changelog 路径目前仅适用于 Cloud。不要因为工具接受某条命令，就将其扩展到 Stack 产品。

What to collect

需要收集的信息

The same facts serve all three destinations, so gather them once: a title that describes the issue rather than the investigation, the affected product and versions, what users actually experience, the workaround or an explicit statement that there is none, and a link to the tracking issue.

三个目标位置所需的事实相同，因此只需收集一次：描述问题而非调查过程的标题、受影响的产品和版本、用户的实际体验、变通方案或明确说明不存在变通方案，以及跟踪 Issue 的链接。

Match the page you are targeting

与目标页面的结构保持一致

For the two Markdown destinations, read the page before drafting anything and follow the shape already there. The formats differ by product, and a contribution in the wrong shape gets rewritten. Kibana's page uses a

::::{dropdown}

block per issue with an

Applies to:

line and Details and Workaround headings. Elasticsearch's uses a

## <version>

section per release with prose bullets. Do not carry one product's format to another, and do not invent a third.

For the changelog destination, the versions go in the products slot,

-separated, and the workaround goes in

action

docs-builder changelog note \
  --type known-issue --title "<title>" --products "<product> <versions> ga"

Hand off to

docs-fix-changelog

, which composes and checks that command. Do not reimplement its field rules here.

对于两个 Markdown 目标，应在起草前阅读页面，并遵循其中已有的结构。不同产品的格式不同，格式错误的内容会被重写。Kibana 页面为每个问题使用一个

::::{dropdown}

块，并包含

Applies to:

行以及 Details 和 Workaround 标题。Elasticsearch 页面则按发布版本使用

## <version>

章节和文字项目符号。不要将一个产品的格式套用到另一个产品，也不要创造第三种格式。

对于 changelog 目标，版本放在 products 位置，以

分隔，变通方案放在

action

中：

docs-builder changelog note \
  --type known-issue --title "<title>" --products "<product> <versions> ga"

移交给

docs-fix-changelog

，由其组织并检查该命令。不要在此重新实现其字段规则。

When the requester cannot make the change themselves

当请求方无法自行修改时

Common when support relays an issue in a product they do not own. File it rather than dropping it: use

internal-request.yml

, title it

[Internal]: Add known issue to <product> <version> release notes

, name the exact destination from the table so nobody has to rediscover it, and put the collected facts in the Description as labeled lines. Say plainly that the ask is a release-notes known issue, not a change to a documentation page.

For a stack product, also ask who is expected to make the edit — product team or writer varies by team — and record the answer in the issue.

当支持团队转述其不负责的产品问题时，常见这种情况。不要丢弃请求，而应提交 Issue：使用

internal-request.yml

，标题设为

[Internal]: Add known issue to <product> <version> release notes

，并准确写出上表中的目标位置，避免他人重新判断。将收集到的事实以带标签的行形式放入 Description。明确说明该请求针对发行说明中的已知问题，而不是文档页面的变更。

对于 Stack 产品，还应询问预计由谁负责修改——产品团队或作者会因团队而异——并记录答案。

Not a docs request

不属于文档请求的情况

A product bug, a support question, or a feature request belongs in the product's own workflow, and routing it there gets the requester a faster answer. Say so and stop. If the product misbehaves and the docs are accurate, that is a product issue.

产品缺陷、支持问题或功能请求应进入产品自身的工作流程，将其路由过去能让请求方更快得到答复。应如实说明并停止。如果产品行为异常而文档准确无误，则应提交产品 Issue。

Step 4: Fill the fields

步骤 4：填写字段

Interview only for what you do not already have from Step 1. Required fields are marked ✱.

[Internal]
— internal documentation request

Field	Heading in the body	Notes
Description ✱	`### Description`	Structure it as What / When / Why, which is the placeholder the form suggests
Resources ✱	`### Resources`	Implementation PR, scoping issue, internal design doc. Mark internal-only links as internal. For a feature a writer has to click through, also how to reach a test environment with data that exercises it — see Step 1
Deployment methods ✱	`### Which deployment methods does this change impact?`	Elastic On-Prem and Cloud (all) · On-Prem only (ECE, ECK, or self-managed) · Elastic Cloud (Hosted and Serverless) only · Cloud Hosted only · Cloud Serverless only · Unknown
Feature differences	`### Feature differences`	Required in practice when more than one deployment method is affected — tell the requester the tagging depends on it
Stack release ✱	`### What Elastic Stack release is this request related to?`	`N/A` for serverless-only work. Confirm the live option list; do not offer a version the template no longer lists
Serverless release	`### Serverless release`	When you expect promotion to the serverless production environment
Collaboration model ✱	`### Collaboration model`	Docs writes the first draft · the product or engineering team does · collaborate · unknown
Point of contact ✱	`### Point of contact.`	`Main contact: @handle` plus stakeholders. At least one real `@mention` — a name without a handle is not a contact

[Community]
— affected page or section ✱ (with the URL) · what should change and why you expected something else ✱ · additional info.

[UI copy]

Description ✱ — What / When / Why, plus whether the copy is new or being edited.
Related links and assets ✱ — Figma, GitHub epic and issues, how to find the text in production, a testing environment. No credentials.
Product area · collaborators ✱ (PM, designer, developer) · timeline and deliverables, noting where serverless and stateful timing differs.

Time-sensitive copy work also needs a direct ping to the responsible writer or docs team. Tell the requester that the issue alone is not a fast path.

[API]
— was the documentation helpful ✱ (Yes · Partly · No) · affected page ✱ · description of the experience.

[Website]
(public) and [Issue]
(private) — confirmation that this is about documentation content ✱ · type of issue (Inaccurate · Missing information · I can't find what I'm looking for · Other) · affected page URL ✱ · what happened ✱ · additional info. Same fields in both repos; only the prefix and label differ.

[KB Promotion]
(private only)

Required ✱ — KB article title · internal link to the article · motivation, which has to name the gap it fills in the public docs rather than restating what the article says.
Optional — content scope (full or partial) · destination proposal, new page or integrated into existing pages · whether they draft it or docs does · additional notes.

Do not press for the optional fields. The template says outright that the requester can leave them to the docs team, which makes the final call on structure and destination — a useful article with a clear why is already a complete request.

[SEO request]
(private only) — a Markdown template, so these are

##

sections: URLs or paths affected · description of the discoverability or search visibility goal · priority (High · Medium · Low, as a checklist) · timeline with expected start and end dates · dependencies, meaning related issues and pull requests · contact person · notes.

仅访谈步骤 1 中尚未获得的信息。必填字段标记为 ✱。

[Internal]
——内部文档申请

字段	正文标题	说明
Description ✱	`### Description`	按 What / When / Why 组织内容，这也是表单建议的占位结构
Resources ✱	`### Resources`	实现 PR、范围界定 Issue、内部设计文档。将仅限内部访问的链接标记为 internal。对于作者必须点击验证的功能，还需说明如何访问包含相关数据的测试环境——见步骤 1
Deployment methods ✱	`### Which deployment methods does this change impact?`	Elastic On-Prem and Cloud (all) · On-Prem only (ECE, ECK, or self-managed) · Elastic Cloud (Hosted and Serverless) only · Cloud Hosted only · Cloud Serverless only · Unknown
Feature differences	`### Feature differences`	实际上，当影响多个部署方式时必填——应告知请求方，标签设置取决于这些信息
Stack release ✱	`### What Elastic Stack release is this request related to?`	仅涉及 serverless 的工作填写 `N/A` 。确认实时选项列表；不要提供模板中已不存在的版本
Serverless release	`### Serverless release`	预计何时在 serverless production environment 中推广
Collaboration model ✱	`### Collaboration model`	Docs writes the first draft · the product or engineering team does · collaborate · unknown
Point of contact ✱	`### Point of contact.`	`Main contact: @handle` 以及利益相关者。至少包含一个真实的 `@mention` ——只有姓名而没有 handle 不能作为联系人

[Community]
——受影响的页面或章节 ✱（附 URL）· 应修改什么，以及为什么原本预期结果不同 ✱ · 附加信息。

[UI copy]

Description ✱——What / When / Why，以及该文案是新增还是修改。
Related links and assets ✱——Figma、GitHub epic 和 Issue、在生产环境中查找文本的方法、测试环境。不得包含凭据。
Product area · collaborators ✱（PM、设计师、开发人员）· 时间线和交付物，并说明 serverless 与 stateful 的时间差异。

有时限要求的工作还需要直接提醒负责的作者或文档团队。应告知请求方，仅提交 Issue 并不是快速通道。

[API]
——文档是否有帮助 ✱（Yes · Partly · No）· 受影响的页面 ✱ · 使用体验描述。

[Website]
（公共）和 [Issue]
（私有）——确认此问题涉及文档内容 ✱ · 问题类型（Inaccurate · Missing information · I can't find what I'm looking for · Other）· 受影响页面的 URL ✱ · 发生了什么 ✱ · 附加信息。两个仓库的字段相同，仅前缀和标签不同。

[KB Promotion]
（仅私有）

必填 ✱——KB 文章标题 · 文章的内部链接 · 推广动机，必须说明它填补公共文档中的哪个缺口，而不是重复文章内容。
可选——内容范围（完整或部分）· 建议目标位置，新页面或整合到现有页面 · 由对方还是 Docs 起草 · 补充说明。

不要追问可选字段。模板明确说明请求方可以将其留给文档团队，由文档团队最终决定结构和目标位置——一篇理由清晰、包含有用文章的完整申请已经足够。

[SEO request]
（仅私有）——由于它是 Markdown 模板，因此使用

##

章节：受影响的 URL 或路径 · 可发现性或搜索可见性目标说明 · 优先级（High · Medium · Low，以复选框形式）· 包含预计开始和结束日期的时间线 · 依赖项，即相关 Issue 和 pull request · 联系人 · 备注。

Step 5: Make the request legible to a writer

步骤 5：让请求便于作者理解

The issue has one reader: the technical writer who picks it up. Two shapes of request routinely fail that reader, and untangling them is your job here, not theirs after the issue lands.

Issue 只有一位读者：接手工作的技术作者。以下两种请求形态经常会让作者无法继续，而理清它们是你的职责，而不是作者在 Issue 提交后的职责。

Turn implementation detail into user-facing behavior

将实现细节转化为面向用户的行为

A request written from the development side says what was built. A writer needs what changed for the person using the product. When the request is a brain dump, or reads as a summary of the implementation, do not paste it into the Description — restructure it.

For each fact in the dump, ask what it lets a user do, see, configure, or avoid. That answer is what belongs in the Description, because it is the part that can be documented and later verified.

Written from the dev side	What the writer needs
Refactored the rule task runner to poll in batches	Whether a user gets faster alerts, a new setting, a changed limit, or nothing they can perceive
Added `execution_status` to the alerting API response	What the field tells a user, and when they would have reason to read it
Shipping behind feature flag `x.y.enabled`	Whether users can turn it on and how, or that it is not available to them yet

Four rules hold this together:

Never guess the user-facing behavior. A plausible-sounding invention is worse than a blank, because the writer can't tell it apart from a fact — if you can't derive it from what the requester gave you, ask.
Move implementation detail, do not discard it. PR links, design docs, and flag names go under Resources, where they are depth for a writer who wants it rather than a wall in front of the request. Tell the requester what you moved and where.
A fact you could not translate becomes an explicit open question in the issue. One line a writer can resolve beats a paragraph they have to decode.
Drop nothing silently. If something in the dump has no place in the issue, say so when you present the draft, so the requester can overrule you.

从开发侧撰写的请求说明的是构建了什么。作者需要知道的是产品使用者因此发生了什么变化。当请求是一份未经整理的信息倾倒，或读起来像实现摘要时，不要将其直接粘贴到 Description 中——应重新组织。

对于信息倾倒中的每一项事实，询问它让用户能够做什么、看到什么、配置什么或避免什么。答案才应放入 Description，因为这才是可被记录和后续验证的部分。

从开发侧撰写	作者需要什么
重构了 rule task runner，使其批量轮询	用户是否会获得更快的告警、新设置、不同的限制，或任何可感知的变化
在 alerting API 响应中增加了 `execution_status`	该字段向用户提供什么信息，以及用户何时会有理由查看它
通过 feature flag `x.y.enabled` 发布	用户能否自行启用以及如何启用，或者该功能目前尚不可用

以下四项规则共同保证准确性：

绝不猜测面向用户的行为。 听起来合理的臆造比留空更糟糕，因为作者无法区分臆造与事实——如果无法从请求方提供的内容中推导出来，就应询问。
移动实现细节，而不是丢弃。 PR 链接、设计文档和 flag 名称应放入 Resources，将其作为作者需要时可查阅的深度信息，而不是挡在作者面前的信息墙。应告知请求方移动了哪些内容以及移动到了哪里。
无法转化为用户行为的事实会成为 Issue 中明确的开放问题。 一行供作者解决的问题，胜过一段需要作者自行解读的描述。
不要静默丢弃任何内容。 如果信息倾倒中的某项内容在 Issue 中没有位置，应在展示草稿时说明，以便请求方提出异议。

Check the request against the code it points to

根据请求指向的代码检查请求

When the request links an implementation pull request or commit, read it. A linked code change pins the repository, the ref, and the version, which makes it the one claim you can check without guessing which source to trust. Skip this whole section when no code change is linked, and never go hunting for one.

gh pr view <n> --repo <owner/repo> --json title,body,state,mergedAt,baseRefName,files
gh pr diff <n> --repo <owner/repo>

Pass the number with

--repo

, or a full PR URL. The shorthand

gh pr view elastic/kibana#12345

does not work —

gh

reads it as a branch name and reports no PR found, which looks like a missing pull request rather than a bad command.

Then compare what the requester says shipped against what the diff shows:

The diff	What to do
Supports the claim	File it as described
Supports part of it, or less than claimed	Narrow the request to what the diff shows, and say in the issue which part you could not confirm
Shows an older state than the request describes	Ask whether the request is still current before filing
Is a refactor, a test change, or internal-only work that does not match the claim	Stop and ask. Do not scope docs work for a user-facing change the code does not show

Three things to get right, because each is a way to be confidently wrong:

Version. The pull request's
```
baseRefName
```
says which branch it landed on. Cross-check that, plus its version labels and any backport, against the release the requester gave you — a request tagged 9.4 describing a change that landed on 8.19 is worth catching before a writer plans around it. See When the change replaces something already documented for why a backport matters here.
Absence proves nothing. A claim missing from the diff is not false — the diff is one change, not the whole product. Only a direct conflict is worth raising.
Matching is not verification. Say what matched and where. An unmerged pull request describes intended behavior that can still change, so note that in the issue rather than presenting it as settled. Never write that a request is technically correct because a diff agreed with it.

当请求链接到实现 pull request 或 commit 时，应阅读它。链接的代码变更会确定仓库、ref 和版本，因此这是无需猜测信息来源即可核实的唯一一项声明。如果没有链接代码变更，则跳过整个章节，也绝不能主动四处寻找。

gh pr view <n> --repo <owner/repo> --json title,body,state,mergedAt,baseRefName,files
gh pr diff <n> --repo <owner/repo>

传递编号时应使用

--repo

，或提供完整 PR URL。简写形式

gh pr view elastic/kibana#12345

不起作用——

gh

会将其解析为分支名并报告找不到 PR，这看起来像缺少 PR，而不是命令错误。

然后比较请求方声称已发布的内容与 diff 显示的内容：

Diff	如何处理
支持该声明	按描述提交 Issue
仅支持部分内容，或支持程度低于声明	将请求范围缩小到 diff 能够证明的范围，并在 Issue 中说明哪一部分无法确认
显示的状态早于请求描述的状态	询问请求是否仍然有效，然后再提交
属于重构、测试变更或内部工作，与声明不符	停止并询问。不要为代码中未体现的用户可见变更界定文档工作范围

以下三点必须正确处理，因为它们都容易导致“自信地犯错”：

版本。 Pull request 的
```
baseRefName
```
表明它落在哪个分支上。应将该信息、版本标签及任何回移植情况与请求方给出的发布版本交叉核对——一个标记为 9.4、实际在 8.19 落地的变更值得在作者规划工作前发现。请参阅当变更替换已有文档内容时，了解回移植为何重要。
缺失不能证明任何事情。 Diff 中没有出现某项声明，并不表示该声明错误——diff 只是一次变更，不代表整个产品。只有直接冲突才值得提出。
匹配不等于验证。 应说明匹配了什么以及在哪里匹配。未合并的 pull request 描述的是仍可能变化的预期行为，因此应在 Issue 中注明，而不能将其描述为已经确定的行为。绝不能因为 diff 与请求一致，就声称该请求在技术上正确。

Treat proposed wording as source material, not as final copy

将建议文案视为素材，而不是最终文案

Sometimes a requester writes the exact paragraph they want added, and sometimes that is precisely what the docs need. Often it is another paragraph on a page that is already overloaded — and a writer who is overwhelmed, new to that area of the docs, or not in a position to push back will paste it in unquestioned. Separate the information from the wording so that the choice stays open:

The substance goes in the Description, as facts.
The requester's text goes under a clearly labeled
```
**Suggested wording**
```
, presented as a suggestion to the writer and never as the change being requested. The labeling is the whole guard — text that arrives looking like a decision gets treated as one.
The Description states what the reader needs to accomplish, which is what lets the writer own placement and framing. A page or section the requester has in mind is recorded as a suggestion, and the issue says plainly that placement is the writer's call.

When the request asks for a whole new page, give the writer what they need to judge that without making the call yourself. Run

find_related_docs

on the topic and list the closest existing pages in the issue. Often one of them should gain a section instead, which is the smaller change and the cheaper one to maintain — but that is the writer's decision. The issue's job is to surface the candidates, not to pre-empt the choice. If the request really is a new page,

docs-content-type-checker

has the definitions that decide whether it is a how-to, an overview, a tutorial, or troubleshooting.

Ask why the text is verbatim, because the answer changes how it is filed:

Why it is verbatim	How to file it
The exact string matters — error text, a log message, a config sample, CLI output	Keep it verbatim and say why, so nobody paraphrases a string users will match against
Legal, security, or support reviewed this specific copy	Keep it verbatim, name the review, and link it
Writing it was faster than explaining it	File it as Suggested wording. The facts inside it are the actual request

Then check it against the page. Step 2's docs search tells you whether the proposed text repeats something the page already says; when it does, put that in the issue. "This is already covered here, and here is what it is missing" is a far cheaper issue to resolve than "add this paragraph."

有时请求方会准确写出希望添加的段落，有时这正是文档所需的内容。但很多时候，该段落恰好位于一个已经过度臃肿的页面上——面对这种情况，作者可能感到不知所措、不熟悉该文档领域，或无法对页面结构提出异议，于是会不加质疑地粘贴其内容。应将信息与措辞分离，让作者保留选择权：

实质内容应作为事实放入 Description。
请求方的文字应放在明确标注的
```
**Suggested wording**
```
下，作为给作者的建议，而不是所请求变更的既定内容。标注本身是关键——看起来像决定的内容往往会被当作决定。
Description 应说明读者需要完成什么，从而让作者自行决定内容的位置和表达方式。请求方设想的页面或章节仅作为建议记录，并明确说明位置由作者决定。

当请求涉及整个新页面时，应为作者提供其判断需求所需的信息，而不要替作者做决定。针对该主题运行

find_related_docs

，并在 Issue 中列出最接近的现有页面。它们中通常有一个更适合新增章节，这通常是范围更小、维护成本更低的改动——但这属于作者的决定。Issue 的职责是提供候选页面，而不是预先替作者选择。如果确实需要新页面，

docs-content-type-checker

中包含用于判断其应为 how-to、overview、tutorial 还是 troubleshooting 的定义。

应询问为何逐字提供文本，因为答案会改变提交方式：

逐字提供的原因	提交方式
精确字符串很重要——错误文本、日志消息、配置示例或 CLI 输出	保持原文，并说明原因，避免他人改写用户需要匹配的字符串
法律、安全或支持团队评审过这段具体文案	保持原文，注明评审方并提供链接
写文案比解释需求更快	将其作为 Suggested wording 提交，文案中的事实才是实际请求

然后将其与页面进行比对。步骤 2 的文档搜索会告诉你建议文本是否与页面已有内容重复；如果重复，应在 Issue 中指出。“这里已经涵盖此内容，那里缺少此内容”比“添加这个段落”更容易让作者处理。

Step 6: Draft the issue

步骤 6：起草 Issue

Write the draft to a scratch file so you can file it with

--body-file

; a multi-paragraph body passed through

--body

on the command line is where quoting goes wrong.

Body format. GitHub renders a submitted form as

### <field label>

followed by the value. Mirror that exactly, in the template's field order, so the issue looks like every other one the triage rotation reads. Omit an optional field you have no answer for; never leave a heading with

_No response_

that you could have filled.

Title. Specific enough to triage without opening. If the requester started from a Report an issue link, replace the placeholder text rather than filing it.

✅ Do this	❌ Don't do this
Add a new section on air-gapped configuration	Update docs
Website Link in Elastic OpenTelemetry logs tutorial is broken	Website some-doc-url
Python code snippet is not valid in tutorial X	This docs is wrong1!1

Specific is one axis; written for the reader is the other — the one an engineering handoff usually fails, since the request often carries the pull request's title, written for reviewers. Reframe it as what a user can now do:

✅ User-facing	❌ Dev-facing
Save Markdown panels to the Visualize library	Add library support for Markdown embeddable
Options List controls now default to Contains search	Change default search technique in optionsList

If you could not confirm part of the request against the linked code, title only the part you could.

Description. It needs a definition of done — the change the requester wants to see — and the why behind it. "This doc must be improved" gives a writer nothing to build or to verify. "A customer had trouble with a recent Kafka change; a note in the documentation would have helped them resolve it faster and prevented a support ticket" gives them both.

Availability. Close the description with one plain sentence saying where and when the change applies, built from the deployment method and release answers you already collected:

Applies from 9.5.0 and in serverless. · Stack only, from 9.5.0 — not available in serverless. · Serverless only. · Applies from 9.5.0 (technical preview) and in serverless.

The template collects those answers in separate dropdowns, so one sentence in the description saves the writer reassembling them, and gives

docs-applies-to-tagging

what it needs to choose the tags. Do not guess the serverless half: if the requester does not know, write that it is unconfirmed rather than implying it applies everywhere.

When the change replaces something already documented (see Step 2), one sentence isn't enough — give both states, with the patch boundary:

The Roles UI category is Alerting V2 from 9.5.4 and 9.6.0, and in serverless. Stack 9.5.0 through 9.5.3 still show Alerting.

Links. Every affected documentation page, plus the tickets and discussions the request came out of. For internal requesters, summarize the key points of an internal thread instead of relying on a link only some readers can open, and mark internal-only links as such. For community requesters, link the public discussion, forum post, or blog post that gives the background.

Then check your own draft before showing it:

- [ ] Title is specific, carries the template's prefix, and reads for a user rather than a pull request reviewer
- [ ] Description states the change and the why, and a writer could tell when it is done
- [ ] Description is what a user can do, not how it was built — anything you could not translate is an open question, not a guess
- [ ] Description ends with a one-sentence availability note
- [ ] If the change replaces something already documented, the old value and the releases that still ship it are in the issue, and the suggested edit asks for a version-scoped split rather than a rewrite
- [ ] Every gap named is real, and narrowed to what any linked code change supports
- [ ] Proposed wording is labeled a suggestion with placement left to the writer, unless the exact string is required and you said why
- [ ] Every affected page, ticket, and discussion is linked, internal-only ones marked
- [ ] Every required field of the chosen template is answered
- [ ] One single, testable problem
- [ ] Template, prefix, and labels all come from the repository being filed into
- [ ] No sensitive content in a body headed for a public repo
- [ ] Contacts are real @mentions

A box you cannot check is a question for the requester, not something to paper over.

将草稿写入临时文件，以便使用

--body-file

提交；在命令行中通过

--body

传递多段正文，正是引号容易出错的地方。

正文格式。 GitHub 将提交的表单呈现为

### <field label>

后跟对应值。应完全镜像该格式，并按照模板的字段顺序排列，使 Issue 与分流轮值中处理的其他 Issue 保持一致。如果某个可选字段没有答案，应省略该字段；绝不能留下一个本可填写却写着

_No response_

的标题。

标题。 应足够具体，使分流人员无需打开正文即可判断。标题应具体到无需打开正文即可完成分流。如果请求方从 Report an issue 链接发起，应替换占位文本，而不是直接提交。

✅ 应该这样写	❌ 不应这样写
Add a new section on air-gapped configuration	Update docs
Website Link in Elastic OpenTelemetry logs tutorial is broken	Website some-doc-url
Python code snippet is not valid in tutorial X	This docs is wrong1!1

具体性是一个维度；面向读者则是另一个维度，也是工程交接经常失败的方面，因为请求通常直接使用 pull request 面向评审者的标题。应重新表述为用户现在能够做什么：

✅ 面向用户	❌ 面向开发者
Save Markdown panels to the Visualize library	Add library support for Markdown embeddable
Options List controls now default to Contains search	Change default search technique in optionsList

如果无法根据链接的代码确认请求中的某一部分，标题中只能写已确认的部分。

Description。 它需要包含完成定义——请求方希望看到的变更——以及背后的原因。“这份文档必须改进”无法给作者提供任何可构建或可验证的内容。“一位客户在处理最近的 Kafka 变更时遇到困难；文档中的说明本可帮助他们更快解决问题并避免提交支持工单”则同时提供了两者。

适用范围。 根据已经收集到的部署方式和发布版本答案，在描述结尾用一句 plain sentence 说明变更在哪里、从何时起适用：

Applies from 9.5.0 and in serverless. · Stack only, from 9.5.0 — not available in serverless. · Serverless only. · Applies from 9.5.0 (technical preview) and in serverless.

模板将答案分别放在不同下拉选项中，因此描述中的这一句话可以避免作者重新组合这些信息，并为

docs-applies-to-tagging

提供选择标签所需的信息。不要猜测 serverless 部分：如果请求方不知道，应写明尚未确认，而不是暗示它适用于所有环境。

当变更替换已有文档内容时（见步骤 2），一句说明并不足够——应同时给出两种状态及其补丁版本边界：

The Roles UI category is Alerting V2 from 9.5.4 and 9.6.0, and in serverless. Stack 9.5.0 through 9.5.3 still show Alerting.

链接。 应包含每个受影响的文档页面，以及请求来源的 ticket 和讨论。对于内部请求方，应概括内部讨论中的关键要点，而不是只依赖部分读者才能打开的链接，并标记仅限内部访问的链接。对于社区请求方，应链接提供背景信息的公开讨论、论坛帖子或博客文章。

然后在展示草稿前自行检查：

- [ ] Title is specific, carries the template's prefix, and reads for a user rather than a pull request reviewer
- [ ] Description states the change and the why, and a writer could tell when it is done
- [ ] Description is what a user can do, not how it was built — anything you could not translate is an open question, not a guess
- [ ] Description ends with a one-sentence availability note
- [ ] If the change replaces something already documented, the old value and the releases that still ship it are in the issue, and the suggested edit asks for a version-scoped split rather than a rewrite
- [ ] Every gap named is real, and narrowed to what any linked code change supports
- [ ] Proposed wording is labeled a suggestion with placement left to the writer, unless the exact string is required and you said why
- [ ] Every affected page, ticket, and discussion is linked, internal-only ones marked
- [ ] Every required field of the chosen template is answered
- [ ] One single, testable problem
- [ ] Template, prefix, and labels all come from the repository being filed into
- [ ] No sensitive content in a body headed for a public repo
- [ ] Contacts are real @mentions

无法勾选的项应作为问题询问请求方，而不是设法掩盖。

Step 7: Get approval, then file

步骤 7：获得批准后提交

Show the full draft — repository, title, labels, and body — and ask whether to file it, change it, or hold it. Wait for an answer.

On approval:

gh issue create --repo <owner/repo> \
  --title "<prefix><title>" \
  --body-file "$DRAFT" \
  --label <label>

Then report the issue URL and what happens next: the docs team triages and prioritizes it, and will ask for clarification if something is unclear. Two things worth telling the requester:

Unanswered feedback on an issue can get it closed, and reopening it after an edit is fine.
An internal requester can link the new public docs issue from the internal support case or private issue it came from, which puts a link in the issue's GitHub timeline for people inside Elastic.

gh issue create

fails, read the error before doing anything else, and never resolve it by changing the repository on your own. Two failures land here and they need opposite responses.

The CLI is the problem.

gh: Not logged into any GitHub hosts

, or a missing scope, or an SSO authorization error. The draft is fine and the requester's browser session probably works even though the token does not, so open the create page prefilled instead:

gh issue create --repo <owner/repo> --web \
  --title "<prefix><title>" --body-file "$DRAFT"

--web

builds a URL rather than calling the API, so it does not depend on the token. A long body can exceed the maximum URL length, and

gh

refuses rather than truncating — fall back to the paste below when it does.

The repository is unreachable.

GraphQL: Could not resolve to a Repository with the name '<owner/repo>'

. GitHub returns 404 for a private repository you cannot see, so this message is identical whether the repository does not exist or the requester simply lacks access — and for

elastic/docs-content-internal

it is almost always access. Do not tell them to paste it into the template: they cannot open that repository in a browser either. Ask which they want:

Get access first — stop and keep the draft. Say what to request.
File publicly instead — only when the sensitive content can come out. Summarize the key points, link the internal source and mark it internal-only, then re-route through Step 3 for the public template, prefix, and labels. Never carry the private body across unchanged.

In both cases the draft survives, which is the point — a draft the requester can file themselves beats a failed command. Hand back the title, the labels to add by hand, and the body in Step 6's

### Field label

format. It won't paste into a form's separate input boxes, but it pastes into a blank issue, which

docs-content

still allows.

展示完整草稿——仓库、标题、标签和正文——并询问是提交、修改还是暂缓。等待回复。

获得批准后：

gh issue create --repo <owner/repo> \
  --title "<prefix><title>" \
  --body-file "$DRAFT" \
  --label <label>

然后报告 Issue URL 以及后续流程：文档团队会对其进行分流和优先级排序，并在内容不清楚时提出澄清请求。以下两点值得告知请求方：

Issue 中未得到回复的反馈可能导致其被关闭，编辑后重新开启也没有问题。
内部请求方可以从最初的内部支持案例或私有 Issue 链接到新创建的公共文档 Issue，从而在 Issue 的 GitHub timeline 中为 Elastic 内部人员留下链接。

如果

gh issue create

失败，必须先阅读错误信息，再采取任何其他操作，绝不能自行更改仓库来解决。常见两类失败需要采用相反的处理方式。

CLI 是问题所在。 出现

gh: Not logged into any GitHub hosts

、缺少 scope 或 SSO 授权错误时，草稿本身没有问题，而且请求方的浏览器会话可能可以正常工作，因此应改为打开预填的创建页面：

gh issue create --repo <owner/repo> --web \
  --title "<prefix><title>" --body-file "$DRAFT"

--web

会构建 URL，而不是调用 API，因此不依赖 token。长正文可能超过 URL 长度上限，

gh

会拒绝而不会截断；出现这种情况时，应改用下面的粘贴方式。

仓库无法访问。 出现

GraphQL: Could not resolve to a Repository with the name '<owner/repo>'

时，GitHub 会为请求方无权访问的私有仓库返回 404，因此该消息在仓库不存在和请求方缺少访问权限这两种情况下完全相同——对于

elastic/docs-content-internal

，几乎总是权限问题。不要告诉对方粘贴到模板中：他们同样无法在浏览器中打开该仓库。应询问对方希望采用哪种方式：

先获取访问权限——停止操作并保留草稿。说明需要申请什么权限。
改为公开提交——仅当敏感内容可以公开时适用。概括关键要点，链接内部来源并标记其仅限内部访问，然后重新执行步骤 3，以选择公共模板、前缀和标签。绝不能原样沿用私有正文。

无论哪种情况，草稿都会保留下来，而这正是重点——一份请求方可以自行提交的草稿，胜过一条失败的命令。应交回标题、需要手动添加的标签，以及步骤 6 中采用

### Field label

格式的正文。它无法粘贴到表单的独立输入框中，但可以粘贴到空白 Issue 中，而

docs-content

仍允许创建空白 Issue。

References

参考资料

Sources this skill encodes.

How to create good docs issues
Public issue templates —
```
elastic/docs-content
```
Private issue templates —
```
elastic/docs-content-internal
```

See also. Elastic-internal and behind org access, so it is deliberately not in

sources:

— it cannot be fetched or staleness-checked.

Request documentation support — the intake process, and what happens after the issue is filed: lead times, planning, who to contact. Hand over the link; see Inputs for how.

Companion skills in this catalog. Collect the inputs they need; do not restate their rules here.

```
docs-fix-changelog
```
— composes the
```
known-issue
```
changelog entry, which is the Cloud and serverless destination only
```
docs-applies-to-tagging
```
— turns the version, lifecycle, and deployment answers into
```
applies_to
```
tags. When something changed rather than arrived, it needs both states: the previous value and the releases that still ship it, alongside the new one
```
docs-content-type-checker
```
— the content type definitions that decide what a proposed new page should be

此 skill 编码所依据的来源：

如何创建优质文档 Issue
公共 Issue 模板——
```
elastic/docs-content
```
私有 Issue 模板——
```
elastic/docs-content-internal
```

另请参阅。相关内容属于 Elastic 内部资源且受组织访问权限限制，因此有意未列入

sources:

——无法获取，也无法检查其是否过期。

申请文档支持——负责接收请求的流程，以及 Issue 提交后的后续工作：前置时间、规划方式和联系人。应直接提供该链接；请参阅输入部分中的相关说明。

此目录中的配套 skill。收集它们所需的信息；不要在此重复其规则。

```
docs-fix-changelog
```
——组织
```
known-issue
```
changelog 条目，该方式仅适用于 Cloud 和 serverless 目标位置。
```
docs-applies-to-tagging
```
——将版本、生命周期和部署方式答案转换为
```
applies_to
```
标签。当某项内容是发生变更而非首次出现时，需要同时提供新旧两种状态：旧值及其仍包含该值的发布版本，以及新值及其发布版本。
```
docs-content-type-checker
```
——用于判断建议的新页面应采用何种内容类型的定义。