Writing tldraw SDK documentation The tldraw voice
Write like a colleague walking someone through code they know well. Confident, casual, code-first.
Characteristic patterns:
Have five minutes? Run this command...
That's pretty much it!
Let's add local persistence by passing a persistenceKey prop...
Need to create some shapes? Use Editor#createShapes. Need to delete them? Use Editor#deleteShapes.
What makes it work:
Direct address with "you" and "let's" Questions as transitions ("Need to create some shapes?") Exclamations that feel natural, not forced ("That's pretty much it!") Jump straight to code, explain around it Short sentences between code blocks Confidence without hedging
State facts. Don't soften them.
// Good The Editor class is the main way of controlling tldraw's editor.
// Bad The Editor class can be used to control tldraw's editor.
Density over exposition
Real tldraw docs are code-heavy. A section might be 20 lines of code with 2 sentences of explanation. Don't pad with prose.
Avoid AI tells
These break trust instantly:
Hollow claims: "plays a crucial role", "serves as a testament to" Trailing gerunds: "...ensuring optimal performance" Formulaic transitions: "Moreover,", "Furthermore,", "It's important to note" Promotional language: "robust", "seamless", "empowers developers" Three-item lists: Real writing has 2, 4, 7 items Passive voice: "can be achieved by" — just show how Conversational asides: "(or whatever)", "(if you want)", "(just saying)" Mechanics Sentence case headings: "Custom shapes" not "Custom Shapes" Active voice: "The store validates records" Present tense: "The migration system transforms" Contractions: it's, we've, you'll, don't Frontmatter
title: Feature name status: published author: steveruizok date: 3/22/2023 order: 1 keywords: - keyword1 - keyword2
MDX components API links
Use ClassName or ClassName#methodName for API references:
The Editor class has many methods. Use Editor#createShapes to create shapes.
Code highlighting
Use
```tsx import { Tldraw } from 'tldraw' import { useSyncDemo } from '@tldraw/sync' ```
Images
Tables for API documentation
Use tables for listing methods, options, or properties:
| Method | Description |
| ------------------------ | ---------------------------------------------- |
| Editor#screenToPage | Convert a point in screen space to page space. |
| Editor#pageToScreen | Convert a point in page space to screen space. |
| Value | Description |
| --------- | ---------------------------------------------------- |
| default | Sets the initial zoom to 100%. |
| fit-x | The x axis will completely fill the viewport bounds. |
Code examples
Show code early, explain around it. Don't build up to code with paragraphs of context.
Realistic, minimal // Good: Real shape, real values editor.createShapes([ { type: 'geo', x: 0, y: 0, props: { geo: 'rectangle', w: 100, h: 100 }, }, ])
// Bad: Placeholder nonsense editor.createShape({ type: 'example-type', props: { prop1: 'value1' } })
Context when needed
Full components are fine when showing integration patterns:
export default function App() { return (
Minimal snippets when showing a single API:
editor.setFocusedGroup(groupId)
Structure Overview first
1-2 paragraphs establishing what and why before diving into how.
Progressive complexity
Start with the common case. Add complexity incrementally. Put edge cases later.
Link to examples
End sections with links to relevant examples:
For an example of how to create custom shapes, see our custom shapes example.
Or in a section:
See the tldraw repository for examples of how to use tldraw's Editor API.
Priorities Accuracy — Code must work. API refs must be correct. Clarity — Understand on first read. Brevity — Say it once, move on. Scannability — Short paragraphs, clear headers, lots of code.