Skip to content
JaypieJaypie

Writing Documentation

Prerequisites: Familiarity with Markdown

Overview

Section titled “Overview”

Jaypie documentation is written for coding agents as the primary audience. Documentation must be self-contained, explicit, and directly usable.

Documentation Types

Section titled “Documentation Types”
Type Location Audience
Package README packages/*/README.md Developers, npm
API Docs src/content/docs/docs/ (Astro Starlight) Agents, developers
Prompt Guides packages/mcp/prompts/ AI agents
CLAUDE.md Project root AI agents

Page Template

Section titled “Page Template”
---
title: "Page Title"
---


**Prerequisites:** [packages to install, files that must exist]


## Overview


[2-3 sentences explaining what this covers]


## Quick Reference


[Table or bulleted list of key concepts]


## Usage


[Complete, copy-pasteable code examples]


## API Reference


[Types, parameters, return values in tables]


## Related


- [Link](/docs/path/) - brief description

Writing Style

Section titled “Writing Style”

Crisp and Declarative

Section titled “Crisp and Declarative”
<!-- Good -->
Use `expressHandler` to wrap route handlers.


<!-- Bad -->
You should probably use the expressHandler function when you want to wrap your route handlers.

Tables Over Prose

Section titled “Tables Over Prose”
<!-- Good -->
| Error | Status | Use Case |
|-------|--------|----------|
| `BadRequestError` | 400 | Invalid input |


<!-- Bad -->
The BadRequestError is used when input is invalid and returns a 400 status code.

Complete Examples

Section titled “Complete Examples”
<!-- Good - complete and runnable -->
```typescript
import { expressHandler, NotFoundError } from "jaypie";


export default expressHandler(async (req, res) => {
  const user = await db.users.findById(req.params.id);
  if (!user) throw NotFoundError();
  return { data: user };
});
throw NotFoundError();
## Code Blocks


### Language Tags


Always include language:


```markdown
```typescript
const x = 1;
### Comments Sparingly


```typescript
// Only comment non-obvious code
const GOLDEN_RATIO = 0.618; // Jaypie uses this for "partial" defaults

README Structure

Section titled “README Structure”
# Package Name


Brief description.


## Installation


## Quick Start


## Usage


[Main usage patterns]


## API


[Function signatures and types]


## Related


[Links to related packages]

Prompt Guide Structure

Section titled “Prompt Guide Structure”
# Guide Title


## Purpose
[When to use this guide]


## Prerequisites
[What must exist]


## Steps
[Numbered steps with code blocks]


## Verification
[How to verify success]


## Troubleshooting
[Common issues and solutions]

Formatting Rules

Section titled “Formatting Rules”

One Sentence Per Line

Section titled “One Sentence Per Line”

For version control diffs:

<!-- Good -->
Jaypie provides error handling.
Errors format as JSON:API.
Use NotFoundError for 404 responses.


<!-- Bad -->
Jaypie provides error handling. Errors format as JSON:API. Use NotFoundError for 404 responses.

Headings

Section titled “Headings”
  • # for page title only
  • ## for major sections
  • ### for subsections
  • Don’t skip levels

Lists

Section titled “Lists”

Use - for unordered lists:

- First item
- Second item
- Third item

Use numbers for ordered lists:

1. First step
2. Second step
3. Third step
Section titled “Links”
Section titled “Internal Links”
[Error Handling](/docs/core/error-handling/)
Section titled “External Links”
[GitHub](https://github.com/finlaysonstudio/jaypie)

Tables

Section titled “Tables”

Align columns for readability:

| Column 1 | Column 2 | Column 3 |
|----------|----------|----------|
| Value 1  | Value 2  | Value 3  |

Agent-Specific Patterns

Section titled “Agent-Specific Patterns”

Explicit Prerequisites

Section titled “Explicit Prerequisites”
**Prerequisites:**
- `npm install jaypie`
- Express app configured
- AWS credentials set

Self-Contained Examples

Section titled “Self-Contained Examples”

Don’t assume context. Include imports:

// Good - complete
import { expressHandler, log, NotFoundError } from "jaypie";


export default expressHandler(async (req, res) => {
  log.trace("[getUser] fetching");
  const user = await db.users.findById(req.params.id);
  if (!user) throw NotFoundError();
  return { data: user };
});

Cross-References

Section titled “Cross-References”

Link related pages:

## Related


- [Handler Lifecycle](/docs/core/handler-lifecycle/) - Lifecycle phases
- [Testing](/docs/guides/testing/) - Testing handlers
Section titled “Related”