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:

• Frontmatter with metadata:

title: API Name sidebar_label: Display Name

Description - What the API does

Usage examples - Code examples showing how to use it

Parameters/Options - Document all parameters, options, and return types

Type information - TypeScript types and examples

Related APIs - Links to related documentation

Finding the Right Documentation File

• Identify the package: Check which package the code belongs to (packages/core , packages/rest , etc.)

• Check exports: Look at the package's index.ts or main entry point to see what's exported

• Match the name: Find the corresponding file in docs/{package}/api/

• 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