packages-documentation

# 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