Terra Money 技术文档教程编写规范指南

前言

在区块链技术领域，清晰易懂的技术文档对于开发者体验至关重要。本文将为Terra Money项目文档贡献者提供一套完整的教程编写规范，帮助创建高质量的技术教程内容。

教程定义与定位

Terra Money教程是面向初学者的实践性指南，具有以下核心特征：

1. 从零开始：假设读者没有任何前置知识，仅具备基础技能（如终端操作、代码编辑等）
2. 目标导向：围绕一个具体任务展开，如"创建Terra钱包"或"部署智能合约"
3. 实践优先：包含可执行的代码示例和操作步骤
4. 单一主题：每个教程专注于解决一个特定问题

目标读者分析

Terra教程的主要读者群体是：

• 区块链开发新手
• 刚接触Terra生态的开发者
• 需要快速实现特定功能的实践者

编写时应避免任何专业术语的假设，所有概念都应解释清楚。例如，提到"LCD"时应说明这是"轻客户端守护进程(Light Client Daemon)"的缩写。

写作风格要求

语言表达

• 使用第二人称（"你"）或第三人称
• 避免第一人称（"我们"、"我"、"让我们"）
• 句子简短明了，每段不超过3句
• 避免复杂从句和冗长表达

示例对比：

• 不佳："首先我们需要安装Node.js，然后我们可以..."
• 良好："安装Node.js后，执行以下命令..."

内容组织

• 只包含完成任务必需的信息
• 额外说明内容应链接到专门的解释性文档
• 操作步骤优先，理论解释为辅

文档结构规范

1. 标题设计

• 使用祈使语气（动词开头）
• 首字母大写，其余小写（除非专有名词）
• 明确反映教程内容

示例：

• "# 创建Terra钱包"
• "# 使用Terra.js查询链上数据"

2. 引言部分

• 2-3句话简要说明教程内容
• 概述读者将学到的技能
• 可包含简短的产品背景

示例模板： "本教程将指导你完成在Terra区块链上部署智能合约的全过程。你将学习如何设置开发环境、编写合约代码并部署到测试网。"

3. 先决条件

• 位于引言之后
• 使用无序列表列出所有依赖项
• 包含具体版本要求
• 避免在教程中途引入未列出的依赖

标准格式：

## 先决条件

- Node.js v16+
- Terra Station钱包
- 至少10 LUNA测试网代币
- 基础命令行知识

4. 操作步骤

• 使用编号标题（## 1. 设置环境）
• 复杂步骤分解为子步骤（使用有序列表）
• 每个代码块只包含一个命令
• 确保命令可直接复制执行

示例结构：

## 1. 初始化项目

1. 创建项目目录：

   ```sh
   mkdir terra-project

2. 进入目录并初始化npm：

   cd terra-project
   npm init -y
   

### 5. 结束部分
- 祝贺用户完成教程
- 提供后续学习建议
- 可链接到相关进阶内容

## 格式规范详解

### 代码块处理
- 可执行命令使用sh代码块
- 代码引用使用`反引号`
- 保持代码原貌，不修改大小写或标点
- 避免在代码块中添加注释说明

**正确示例**：
要查询账户余额，使用：
```sh
terrad query bank balances <address>

标题层级

• 二级标题（主要步骤）

• 三级标题（子步骤）

• 避免使用四级及以上标题

列表使用

• 有序列表用于步骤序列
• 无序列表用于并列项
• 每个列表至少包含2项

特殊标注

• 重要提示使用警告框
• 按钮名称加粗（点击提交）
• 避免斜体等复杂样式

警告框示例： :::{admonition} 安全提醒 私钥必须严格保密，切勿提交到版本控制系统。 :::

最佳实践建议

1. 测试教程：亲自按步骤操作一遍，确保无遗漏
2. 用户视角：想象自己是完全的新手
3. 持续迭代：根据用户反馈优化内容
4. 保持更新：随产品版本更新教程内容
5. 简洁为王：删除所有不必要的信息

通过遵循这些规范，我们可以确保Terra Money技术教程保持高质量和一致性，为开发者提供最佳的学习体验。记住，优秀的文档是项目成功的关键因素之一。