Back to Details

write-docs

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Write documentation

编写文档

This skill covers how to write and update tldraw SDK documentation.
本指南介绍如何编写和更新tldraw SDK文档。

Location

存放位置

All documentation lives in 
apps/docs/content/
. The main categories are:
DirectoryPurpose
docs/
SDK documentation articles
releases/
Release notes (see write-release-notes skill)
examples/
Example documentation
getting-started/
Quickstart and setup guides
所有文档都位于
apps/docs/content/
目录下。主要分类如下：
目录用途
docs/
SDK文档文章
releases/
发布说明（请参考write-release-notes技能）
examples/
示例文档
getting-started/
快速入门与设置指南

Process

流程

1. Understand the scope

1. 明确范围

Before writing:
  • Identify the target audience (new users, experienced developers, API reference)
  • Check existing docs that cover related topics
  • Look at relevant examples in 
    apps/examples/
  • Read the API types and comments in the source code
开始写作前：
  • 确定目标受众（新用户、资深开发者、API参考读者）
  • 查阅涵盖相关主题的现有文档
  • 查看
    apps/examples/
    中的相关示例
  • 阅读源代码中的API类型和注释

2. Create the file

2. 创建文件

Create a new 
.mdx
file in the appropriate directory with frontmatter:
yaml
---
title: Feature name
status: published
author: steveruizok
date: 3/22/2023
order: 1
keywords:
  - keyword1
  - keyword2
---
在对应目录下创建新的
.mdx
文件，并添加以下前置内容：
yaml
---
title: Feature name
status: published
author: steveruizok
date: 3/22/2023
order: 1
keywords:
  - keyword1
  - keyword2
---

3. Write the content

3. 撰写内容

Follow the structure:
  1. Overview — 1-2 paragraphs on what and why
  2. Basic usage — The simplest working example
  3. Details — Deeper explanation with more examples
  4. Edge cases — Advanced patterns, gotchas
  5. Links — Related docs and examples
遵循以下结构：
  1. 概述 — 用1-2段文字介绍功能是什么以及为什么需要它
  2. 基础用法 — 最简单的可用示例
  3. 详细说明 — 更深入的解释及更多示例
  4. 边缘情况 — 高级模式、注意事项
  5. 相关链接 — 相关文档和示例

4. Use MDX components

4. 使用MDX组件

API links

API链接

Use 
[ClassName](?)
or 
[ClassName#methodName](?)
for API references:
markdown
The [Editor](?) class has many methods. Use [Editor#createShapes](?) to create shapes.
使用
[ClassName](?)
或
[ClassName#methodName](?)
格式添加API引用：
markdown
The [Editor](?) class has many methods. Use [Editor#createShapes](?) to create shapes.

Code highlighting

代码高亮

Use 
<FocusLines>
to highlight specific lines:
markdown
<FocusLines lines={[2,6,10]}>

\`\`\`tsx
import { Tldraw } from 'tldraw'
import { useSyncDemo } from '@tldraw/sync'
\`\`\`

</FocusLines>
使用
<FocusLines>
组件高亮特定行：
markdown
<FocusLines lines={[2,6,10]}>

\`\`\`tsx
import { Tldraw } from 'tldraw'
import { useSyncDemo } from '@tldraw/sync'
\`\`\`

</FocusLines>

Images

图片

markdown
<Image
	src="/images/api/events.png"
	alt="A diagram showing an event being sent to the editor."
	title="Caption text here."
/>
markdown
<Image
	src="/images/api/events.png"
	alt="A diagram showing an event being sent to the editor."
	title="Caption text here."
/>

Tables for API documentation

API文档表格

Use tables for listing methods, options, or properties:
markdown
| Method                   | Description                                    |
| ------------------------ | ---------------------------------------------- |
| [Editor#screenToPage](?) | Convert a point in screen space to page space. |
| [Editor#pageToScreen](?) | Convert a point in page space to screen space. |
markdown
| Value     | Description                                          |
| --------- | ---------------------------------------------------- |
| `default` | Sets the initial zoom to 100%.                       |
| `fit-x`   | The x axis will completely fill the viewport bounds. |
使用表格列出方法、选项或属性：
markdown
| Method                   | Description                                    |
| ------------------------ | ---------------------------------------------- |
| [Editor#screenToPage](?) | Convert a point in screen space to page space. |
| [Editor#pageToScreen](?) | Convert a point in page space to screen space. |
markdown
| Value     | Description                                          |
| --------- | ---------------------------------------------------- |
| `default` | Sets the initial zoom to 100%.                       |
| `fit-x`   | The x axis will completely fill the viewport bounds. |

5. Verify

5. 验证

Check that:
  • Code examples actually work
  • API links resolve correctly
  • Images have alt text
  • Headings use sentence case
  • No AI tells (see style guide)
检查以下内容：
  • 代码示例可正常运行
  • API链接可正确跳转
  • 图片包含替代文本
  • 标题使用句首大写格式
  • 无AI生成痕迹（请参考风格指南）

References

参考资料

  • Style guide: See 
    ../shared/docs-guide.md
    for voice, tone, and formatting conventions.
  • 风格指南：请查看
    ../shared/docs-guide.md
    获取语气、语调及格式规范。