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, @data-client/react and @data-client/vue
• 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

React and Vue (single source)

docs/core renders twice: React at /docs, Vue at /vue. Never copy a page to make a Vue version. Wrap framework-specific content instead, so shared prose and resources stay in one place:

• :::react / :::vue blocks (use :::: on an outer admonition that contains them)
• :react[...] / :vue[...] for inline words or links
• <FrameworkPlayground> instead of <HooksPlayground>, with shared resource code blocks directly inside and component code blocks in :::react / :::vue
• framework-imports on a code fence for framework-agnostic code (managers, middleware): write @data-client/react imports and Vue pages show @data-client/vue. Examples never import @data-client/core; apps only install the react or vue package
• vue_title:, vue_description: (any vue_<key>:) front matter overrides
• frameworks: [react] front matter for pages with no Vue equivalent
• foo.vue.md replaces foo.md for Vue; only for Vue-only pages or when nothing is shareable

When changing a page, update both framework blocks in the same edit. See website/framework-docs/README.md.

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:

---
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)
• Updated agent skills in .agents/skills that cover the API: references.json for added/renamed/deleted pages, and SKILL.md examples (see .cursor/rules/skills-sync.mdc)

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