home / skills / reactive / data-client / packages-documentation
This skill helps you generate and maintain comprehensive API documentation across core, rest, and graphql packages, improving discoverability and consistency.
npx playbooks add skill reactive/data-client --skill packages-documentationReview the files below or copy the command above to add this skill to your agents.
---
name: packages-documentation
description: Write, update, and format docs for public APIs - API reference, README, docstrings, usage examples, migration guides, deprecation notices
license: Apache 2.0
---
# Package Documentation Writing Guidelines
This guide covers how to write and format documentation for public library interfaces.
## Documentation Structure
The `/docs` folder is organized by package:
- `docs/core/` - Documentation for `@data-client/core` and `@data-client/react`
- `docs/rest/` - Documentation for `@data-client/rest`
- `docs/graphql/` - Documentation for `@data-client/graphql`
Each package documentation has subdirectories:
- `api/` - API reference documentation (one file per public class/function/hook)
- `guides/` - How-to guides and tutorials
- `concepts/` - Conceptual documentation
- `getting-started/` - Getting started guides
## Documentation File Naming
API documentation files should match the exported name:
- `useSuspense.ts` → `docs/core/api/useSuspense.md`
- `RestEndpoint.js` → `docs/rest/api/RestEndpoint.md`
- `Controller.ts` → `docs/core/api/Controller.md`
- `Entity.ts` → `docs/rest/api/Entity.md` (or `docs/core/api/Entity.md`)
## Documentation Format
All API documentation files should include:
1. **Frontmatter** with metadata:
```markdown
---
title: API Name
sidebar_label: Display Name
---
```
2. **Description** - What the API does
3. **Usage examples** - Code examples showing how to use it
4. **Parameters/Options** - Document all parameters, options, and return types
5. **Type information** - TypeScript types and examples
6. **Related APIs** - Links to related documentation
## Finding the Right Documentation File
1. **Identify the package**: Check which package the code belongs to (`packages/core`, `packages/rest`, etc.)
2. **Check exports**: Look at the package's `index.ts` or main entry point to see what's exported
3. **Match the name**: Find the corresponding file in `docs/{package}/api/`
4. **Check guides**: If it's a workflow change, also check `docs/{package}/guides/`
## Examples
### Example 1: Adding a new hook
- **File**: `packages/react/src/hooks/useNewFeature.ts`
- **Action**: Create `docs/core/api/useNewFeature.md` with usage examples and API reference
### Example 2: Changing a method signature
- **File**: `packages/rest/src/RestEndpoint.js` (changing `extend()` method)
- **Action**: Update `docs/rest/api/RestEndpoint.md` with new signature, migration notes, and updated examples
### Example 3: Deprecating an API
- **File**: `packages/core/src/SomeClass.ts` (deprecating `oldMethod()`)
- **Action**:
- Update `docs/core/api/SomeClass.md` with deprecation notice
- Document the replacement API
- Add migration guide if needed
### Example 4: Adding a new option
- **File**: `packages/rest/src/RestEndpoint.js` (adding `newOption` parameter)
- **Action**: Update `docs/rest/api/RestEndpoint.md` to document the new option with examples
## Checklist
Before completing changes to public APIs in `/packages`:
- [ ] Identified all affected public APIs (exports from package entry points)
- [ ] Located or created corresponding documentation files in `/docs/{package}/api/`
- [ ] Updated API reference documentation with changes
- [ ] Added/updated code examples
- [ ] Updated related guides if workflow changed
- [ ] Added migration notes for breaking changes
- [ ] Updated TypeScript examples in documentation
- [ ] Verified documentation builds correctly (if applicable)
## Important Notes
- **Public APIs** are anything exported from the package's main entry point (typically `index.ts` or `src/index.ts`)
- **Internal/private APIs** (prefixed with `_`, not exported, or marked as `@internal`) don't require documentation updates
- When in doubt, **err on the side of documenting** - it's better to have extra documentation than missing documentation
- Documentation should be updated **in the same commit or PR** as the code changes
This skill helps write, update, and format documentation for public TypeScript packages in a monorepo that provides async state management, REST/GraphQL clients, SSE, and hooks. It focuses on API reference files, guides, conceptual docs, examples, migration notes, and deprecation notices organized under docs/{package}. It ensures documentation matches exports, includes TypeScript types and usage examples, and ships with the same commit as code changes.
The skill inspects package exports (index.ts or main entry) to identify public APIs and locates or creates matching files under docs/{package}/api/. It updates frontmatter, descriptions, examples, parameters, and type information, and adds related guides or migration notes when signatures or behavior change. It also enforces filename and folder conventions, checks for deprecation/migration guidance, and verifies documentation examples and TypeScript snippets are present.
How do I find which APIs need documentation updates?
Check package entry points (index.ts or src/index.ts) for exported symbols and compare to files in docs/{package}/api/. Any new or changed export likely needs an API doc update.
Should internal or underscored APIs be documented?
No. Internal APIs (prefixed with _, not exported, or marked @internal) do not require public docs. When unsure, prefer documenting to avoid missing public behavior.