AgentSkillsCN

documentation

撰写高效的文档，包括内联文档、README 结构、API 文档以及代码注释。在编写 README 文件、记录 API 文档、创建架构决策记录、添加内联代码文档，或搭建文档工具链时，可使用此技能。

SKILL.md
--- frontmatter
name: "documentation"
description: 'Write effective documentation including inline docs, README structure, API documentation, and code comments. Use when writing README files, documenting APIs, creating architecture decision records, adding inline code documentation, or setting up documentation tooling.'
metadata:
  author: "AgentX"
  version: "1.0.0"
  created: "2025-01-15"
  updated: "2025-01-15"

Documentation

Purpose: Write clear, maintainable documentation for code and APIs.
Goal: Self-documenting code, useful comments, comprehensive READMEs.
Note: For implementation, see C# Development or Python Development.

When to Use This Skill

  • •Writing or updating README files
  • •Documenting APIs with OpenAPI/Swagger
  • •Creating architecture decision records (ADRs)
  • •Adding inline code documentation
  • •Setting up documentation tooling

Prerequisites

  • •Markdown formatting knowledge

Decision Tree

code
Documenting something?
├─ New project/repo? → README.md (setup, usage, contributing)
├─ Public API?
│   ├─ REST API → OpenAPI/Swagger spec
│   └─ Library → XML docs / docstrings on all public members
├─ Architecture decision? → ADR (docs/adr/ADR-NNN.md)
├─ Complex logic?
│   ├─ WHY it works this way → Code comment
│   └─ HOW to use it → Doc comment / docstring
├─ Code self-explanatory?
│   └─ Yes → No comment needed (good naming > comments)
└─ Inline comment?
    ├─ Explains WHY (business rule, workaround) → Keep it
    └─ Explains WHAT (obvious from code) → Remove it

Documentation Hierarchy

code
Documentation Pyramid:

        /\
       /API\        External API docs (OpenAPI/Swagger)
      /------\
     / README \     Project documentation
    /----------\
   / Inline Docs\   Function/class documentation
  /--------------\
 /  Code Quality  \ Self-documenting code (naming, structure)
/------------------\

Best Code = Minimal comments needed

Self-Documenting Code

Code Should Explain WHAT

code
❌ Bad: Needs comment to understand
  # Check if user can access
  if u.r == 1 or u.r == 2:
    return True

✅ Good: Self-explanatory
  if user.role == Role.ADMIN or user.role == Role.MODERATOR:
    return True

✅ Better: Extract to function
  if user.hasModeratorPermissions():
    return True

Names Should Be Descriptive

code
Variables:
  ❌ d, tmp, data, x
  ✅ daysSinceLastLogin, userCount, orderTotal

Functions:
  ❌ process(), handle(), do()
  ✅ calculateShippingCost(), validateEmailFormat(), sendWelcomeEmail()

Classes:
  ❌ Manager, Handler, Processor, Helper
  ✅ OrderRepository, EmailValidator, PaymentGateway

Best Practices Summary

PracticeDescription
Code firstWrite self-documenting code before adding comments
Document whyExplain intent, not mechanics
Keep updatedWrong docs are worse than no docs
ExamplesShow, don't just tell
AudienceWrite for the reader, not yourself
MinimalDocument what's needed, no more
AccessibleStore docs near the code
VersionedDocs in repo, not external wikis

See Also: API Design • C# Development • Python Development

Scripts

ScriptPurposeUsage
generate-readme.pyAuto-generate README.md from project metadatapython scripts/generate-readme.py [--output README.md]

Troubleshooting

IssueSolution
Documentation out of sync with codeGenerate API docs from code annotations, add doc validation to CI
README too longSplit into separate docs/ files, link from README
Missing API documentationAdd doc comments to all public APIs, generate with Swagger/Redoc

References