docs-doc-review

Review documentation pages for structure, readability, and consistency before release.

12|2|Updated Nov 27, 2024
One-click install
npx skills add https://github.com/Pionpill/retikz --skill docs-doc-review
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: docs-doc-review
Source: https://github.com/Pionpill/retikz/tree/main/.agents/skills/docs-doc-review
Command: npx skills add https://github.com/Pionpill/retikz --skill docs-doc-review

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

这项 Skill 帮你在文档写作完成后,从初级前端工程师的阅读体验出发做独立审稿,定位页面结构是否符合页型规范、双语是否对齐、demo/图示是否足够以及专业术语是否过载等问题,避免作者自嗨式内容影响读者理解。

Core Features & Use Cases

  • 页型结构与一致性检查:组件页/示例页/分组页/Reference 页按既定结构核对,重点检查 zh/en 层级、表格与示例数量对齐。
  • 读者视角可读性评审:判断开头是否先回答“解决什么问题/什么时候用”、专业词是否需要更前置的通俗解释,以及 API 表是否能独立读懂。
  • 对照与 demo 覆盖核查:核对 TikZ/D3 等对照是否集中放到 Comparison / reference(而不是正文散落),检查 demo 是否真实展示差异、是否缺少必要最小示例与图示线索。
  • 双语与三处协同可维护性:验证 contents/ data/ i18n 相关内容是否同步,以及 Related 链接是否指向更合适的下一页。

Quick Start

让你的 AI 依据给定的目标页面路径和 git diff,对 apps/docs/src/contents/**/index.zh.mdx 进行独立审稿,只输出问题清单与修改建议,不直接改稿。

Frequently Asked Questions about docs-doc-review

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I review bilingual documentation for zh/en alignment and structural consistency?

Reviewing bilingual documentation for zh/en alignment involves verifying page-type layouts, matching table and example quantities across language versions, and ensuring synchronized contents, data, and i18n updates. This catches structural deviations and missing translations before release.

What is the best way to check if documentation demos and diagrams sufficiently cover the features?

Checking documentation demo and diagram coverage requires verifying that examples actually demonstrate feature differences and include necessary minimal examples with visual cues. This ensures TikZ and D3 comparisons are centralized in reference sections rather than scattered within main text.

How do I audit documentation readability from a frontend engineer's perspective?

Auditing documentation readability from a frontend engineer's perspective means evaluating whether pages immediately answer what problem is solved and when to use the feature. It checks if technical terms need earlier plain explanations and if API tables can be understood independently.

Can I use an automated review process to audit existing apps/docs pages with git diffs?

Yes, you can use an automated review process to audit existing apps/docs pages by supplying the target page path and git diff. The review then independently analyzes the changes and outputs a problem list with modification suggestions without directly altering the manuscript.

When should I run a documentation consistency check during the release cycle?

You should run a documentation consistency check after writing is complete but before release. This timing allows you to catch page-type structural issues, zh/en misalignment, and insufficient demo coverage while corrections can still be applied to the source mdx files.

Why does my documentation review report show mismatched contents and i18n data?

A documentation review report shows mismatched contents and i18n data when synchronization checks detect that updated page content was not propagated across all three directories. This indicates a maintenance gap where Related links and data files need manual syncing.