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:

---
title: API Name
sidebar_label: Display Name
---

1. •

   Description - What the API does

2. •

   Usage examples - Code examples showing how to use it

3. •

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

4. •

   Type information - TypeScript types and examples

5. •

   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