사용 방법
- 설치 명령을 복사하고 자신의 에이전트 환경에 설치하기 전에 소스 패키지를 확인하세요.
- 필요한 도구, 인증 정보, 지원 환경은 원본 문서에서 확인하세요.
- 입력과 원하는 산출물을 설명하고 출처와 결과를 대조하세요.
npx skills add https://github.com/enitrat/skill-issue --skill sdk-documentation시작 전 확인
- 설치에는 모델 구독, API 한도, 파일 접근 권한이 포함되지 않습니다.
- 별점 수와 설치 수는 활동 지표이며 독립적인 품질·보안 검증이 아닙니다.
원본 Skill 문서
원본 저장소의 제목, 예시, 코드, 표, 링크, 이미지를 유지해 표시합니다.
SDK Documentation Best Practices
Rules for writing clear, scannable, code-forward documentation for public SDKs. Derived from analysis of best-in-class SDK documentation (wagmi, viem, TanStack). Rules are domain-agnostic; examples use generic SDK patterns with occasional web3 illustrations.
Documentation Type Router
Before writing, identify which type of page you're creating. Each type has different rules.
| Question you're answering | Doc type | Template | Key rule |
|---|---|---|---|
| "Help me learn this SDK" | Tutorial (Getting Started) | guides.md → Tutorials | Learning-oriented: guide the reader, eliminate choices, show destination early |
| "Help me accomplish X" | How-to Guide (Task Guide) | guides.md → How-to Guides | Task-oriented: assume competence, action-only, address real-world complexity |
| "What does X do / accept / return?" | API Reference | api-reference.md | Information-oriented: describe only, zero explanation, mirror product structure |
| "Why does X work this way?" | Explanation (Concept/Why page) | tone.md → Explanation Pages | Understanding-oriented: provide context, make connections, admit tradeoffs |
The cardinal sin is mixing types. A tutorial that stops to explain architecture loses the learner. A reference page that teaches loses the practitioner looking up a parameter. An explanation page that includes step-by-step instructions belongs in a how-to guide.
Core Philosophy
| Principle | Meaning |
|---|---|
| Code is the star | Prose exists to introduce, contextualize, and connect code examples |
| Scannable over narrative | Readers skim for answers; structure for rapid lookup |
| Show, don't tell | Diff annotations and working examples beat explanations |
| One concept per step | Never introduce multiple ideas simultaneously |
| Full files, not snippets | Every code block should be runnable in isolation |
| Template rigidly | Predictable structure is a feature, not a limitation |
Quick Reference: Critical Rules
| Category | DO | DON'T | |
|---|---|---|---|
| Voice | "you" for concepts, "we" for tutorials | Passive voice | |
| Tone | Professional-casual, confident | Humorous, condescending, or stiff | |
| Sentences | 10-25 words, active voice | 35+ word run-on sentences | |
| Code examples | Complete runnable files with focus annotations | Partial snippets missing context | |
| Parameters | One ### heading per param with full example | Tables or lists of parameters | |
| Optional params | Indicate via `\ | undefined` in type | "Optional" badges or markers |
| Jargon | SDK-specific terms explained; ecosystem terms assumed | Over-explaining industry basics | |
| Sections | Rigid ordering: Import → Usage → Parameters → Return Type | Freeform section ordering | |
| Cross-refs | Link to related APIs inline and in dedicated sections | "See also" dump at bottom | |
| Warnings | Use a warning admonition for critical info (see your framework's syntax) | Inline bold warnings in prose |
Detailed Guidance by Topic
- Documentation structure: See references/structure.md for site architecture, page templates, navigation, shared content systems
- Narrative tone & explanation pages: See references/tone.md for voice, style, sentence patterns, jargon handling, and explanation/concept page guidance
- Tutorials & how-to guides: See references/guides.md for tutorial rules (learning-oriented), how-to guide rules (task-oriented), progressive disclosure, framework variants
- API references: See references/api-reference.md for parameter docs, return types, TypeScript presentation, cross-referencing
- VitePress setup: See references/vitepress.md for project init, config, markdown extensions, twoslash, code groups, shared includes
- GitBook setup: See references/gitbook.md for Git Sync, content blocks, steppers, OpenAPI integration, reusable content
