Back to Details

technical-docs

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Documentation

文档管理

Technical writing, diagram-as-code, and documentation lifecycle management. Treats docs as code: version-controlled, linted, and CI-verified.
When to use: Creating or updating technical documentation, generating Mermaid diagrams (flowcharts, ERDs, sequence diagrams), auditing documentation coverage against code, or establishing style guides.
When NOT to use: Writing marketing copy, blog posts, or content that does not live alongside code.
技术撰写、图表即代码，以及文档全生命周期管理。将文档视为代码进行处理：版本控制、代码检查和CI验证。
适用场景：创建或更新技术文档、生成Mermaid图表（流程图、ERD、序列图）、针对代码审计文档覆盖率，或制定风格指南。
不适用场景：撰写营销文案、博客文章，或不与代码共存的内容。

Quick Reference

快速参考

TaskApproachKey Point
Doc sync audit
git diff main...HEAD
+ export scan		Compare symbols against doc coverage
Sequence diagramMermaid 
sequenceDiagram
+ 
autonumber
Map messages to function calls
ERDMermaid 
erDiagram
+ Crow's Foot		Derive from Drizzle/Prisma schemas
GitgraphMermaid 
gitGraph
Standardize on main/develop/feature branches
Feature release docOverview + Config + Examples + TroubleshootingChecklist for every new feature
API referenceGenerate from JSDoc/TSDoc annotationsNever write API refs manually
Style guideActive voice + present tense + direct addressConversational but precise
AI-assisted draftingInventory + gap analysis + draft + human reviewAI drafts, humans verify accuracy
Markdown standardYAML frontmatter + language-tagged code blocksAlways specify code block language
Complex diagramsSplit into focused sub-diagrams + subgraphsLimit to 15-20 nodes per diagram
README templateBadges + description + quick start + API linkFirst thing users see; keep under 200 lines
ADR formatStatus, context, decision, consequencesNumbered, immutable once accepted
RunbookSymptoms, diagnosis, resolution, escalationWritten for 3 AM incidents; no ambiguity
任务方法核心要点
文档同步审计
git diff main...HEAD
+ 导出扫描		对比符号与文档覆盖率
序列图制作Mermaid 
sequenceDiagram
+ 
autonumber
映射消息与函数调用
ERD生成Mermaid 
erDiagram
+ Crow's Foot		从Drizzle/Prisma schema推导
Git图制作Mermaid 
gitGraph
标准化main/develop/feature分支
功能发布文档概述 + 配置 + 示例 + 故障排查每个新功能的检查清单
API参考文档从JSDoc/TSDoc注解生成绝不手动编写API参考文档
风格指南制定主动语态 + 现在时 + 直接称呼兼具口语化与精准性
AI辅助撰写盘点 + 缺口分析 + 草稿 + 人工审核AI生成草稿，人工验证准确性
Markdown标准YAML前置元数据 + 带语言标签的代码块始终指定代码块的编程语言
复杂图表制作拆分为聚焦的子图表 + 子图每个图表限制15-20个节点
README模板徽章 + 描述 + 快速开始 + API链接用户第一眼看到的内容；控制在200行以内
ADR格式状态、背景、决策、影响编号管理，一旦确认不可修改
运行手册症状、诊断、解决方法、升级流程为凌晨3点的事故场景撰写；无歧义

Common Mistakes

常见错误

MistakeCorrect Pattern
Using static images for technical diagramsWrite Mermaid syntax inline in Markdown
Generic participant names like 
Agent1
Use specific service or role names matching the architecture
Manually writing API reference docsGenerate from JSDoc/TSDoc annotations in source code
Diagrams with 20+ nodes and no groupingUse subgraphs to group related nodes; limit to 15-20
Documentation referencing outdated defaultsRun doc sync audit comparing exports against coverage
Using "Click here" link textUse descriptive anchor text for accessibility and clarity
Skipping heading hierarchy levelsNever go from H2 to H4; keep hierarchy sequential
Mixing wall-of-text paragraphsUse bullet points, tables, and diagrams for scannability
No ADRs for architectural decisionsRecord decisions with context, status lifecycle, and consequences
错误正确做法
为技术图表使用静态图片在Markdown中内联编写Mermaid语法
使用
Agent1
这类通用参与者名称		使用与架构匹配的具体服务或角色名称
手动编写API参考文档从源代码中的JSDoc/TSDoc注解生成
包含20+节点且无分组的图表使用子图对相关节点分组；限制在15-20个节点
引用过时默认值的文档执行文档同步审计，对比导出内容与覆盖率
使用“点击此处”作为链接文本使用描述性锚文本以提升可访问性和清晰度
跳过标题层级绝不要从H2直接跳到H4；保持层级顺序
大段无格式文本使用项目符号、表格和图表提升可读性
未为架构决策编写ADRs记录决策的背景、状态生命周期和影响

Delegation

任务委派

  • Scan codebase for undocumented exports and documentation gaps: Use 
    Explore
    agent
  • Generate a full documentation site with diagrams from an existing codebase: Use 
    Task
    agent
  • Plan documentation architecture and information hierarchy for a new project: Use 
    Plan
    agent
If the 
mermaid-diagrams
skill is available, delegate complex diagram creation and advanced Mermaid syntax questions to it. Otherwise, recommend: 
npx skills add oakoss/agent-skills --skill mermaid-diagrams
If the 
tldr-expert
skill is available, delegate summary and brief generation to it.
  • 扫描代码库，找出未文档化的导出内容和文档缺口：使用
    Explore
    Agent
  • 从现有代码库生成包含图表的完整文档站点：使用
    Task
    Agent
  • 为新项目规划文档架构和信息层级：使用
    Plan
    Agent
如果
mermaid-diagrams
skill可用，将复杂图表创建和高级Mermaid语法相关问题委派给它。 否则，推荐执行：
npx skills add oakoss/agent-skills --skill mermaid-diagrams
如果
tldr-expert
skill可用，将摘要和简短内容生成任务委派给它。

References

参考资料

  • Writing Style -- Voice, tone, formatting rules, error message guidelines, and structural standards
  • Mermaid Diagrams -- Sequence, ERD, gitgraph, flowchart patterns with anti-patterns and troubleshooting
  • Doc Coverage -- Feature inventory, gap analysis, code-first and doc-first audit workflows
  • AI Collaboration -- AI-human doc workflow, hallucination handling, documentation-as-code practices
  • Markdown Standards -- Frontmatter, headings, code blocks, tables, callouts, and link conventions
  • Runbooks and Onboarding -- Incident runbook templates, escalation paths, and developer onboarding guides
  • 写作风格 -- 语气、语调、格式规则、错误消息指南和结构标准
  • Mermaid图表 -- 序列图、ERD、git图、流程图的模式、反模式及故障排除
  • 文档覆盖率 -- 功能盘点、缺口分析、代码优先和文档优先的审计工作流
  • AI协作 -- AI-人类协作的文档工作流、幻觉处理、文档即代码实践
  • Markdown标准 -- 前置元数据、标题、代码块、表格、提示框和链接约定
  • 运行手册与入职指南 -- 事故运行手册模板、升级路径和开发者入职指南