Sui项目文档风格指南：打造专业易读的技术文档

Sui项目文档风格指南：打造专业易读的技术文档

sui Sui, a next-generation smart contract platform with high throughput, low latency, and an asset-oriented programming model powered by the Move programming language 项目地址: https://gitcode.com/gh_mirrors/su/sui

前言

在区块链技术领域，Sui作为新一代的智能合约平台，其文档质量直接影响开发者体验和项目采用率。本文将深入解析Sui项目的文档编写规范，帮助技术作者创建结构清晰、风格统一的技术文档。

无障碍访问规范

核心原则

• 避免仅依赖颜色或特殊符号强调内容，应使用标准的<strong>和<em>标签
• 所有图片必须包含描述性alt文本和说明性caption
• 图像不能替代文本内容，关键信息必须同时以文字形式呈现

最佳实践示例

![Sui交易流程图](sui-transaction-flow.png)
*图：Sui交易处理流程，展示从提交到确认的完整生命周期*

技术术语处理

缩略语规范

首次出现时必须完整拼写并附带括号缩略形式：

对象能力模型(Object Capability Model，简称OCM)是Sui的核心安全机制。

专有名词

• 正确：Sui Move、Sui CLI
• 错误：SUI move、sui Cli

文档警示系统

三级警示体系

1. 注意(Note)：关键但易忽略的信息

   :::note
   Sui网络每日UTC 00:00执行一次状态更新
   :::
   

2. 提示(Tip)：提高效率的最佳实践

   :::tip
   安装完成后立即备份钱包配置文件
   :::
   

3. 警告(Caution)：可能造成数据丢失的操作

   :::caution
   删除网络前请确认已导出所有密钥
   :::
   

代码呈现规范

代码块使用原则

• 前置说明代码功能
• 后置解析关键元素
• 禁止使用图片替代真实代码

示例对比

// 正确示范
module sui::display {
    /// 批量设置字段
    public fun add_multiple(
        self: &mut Display,
        keys: vector<String>,
        values: vector<String>
    ) { /*...*/ }

语法风格指南

语态与时态

• 主动语态："节点验证交易"而非"交易被节点验证"
• 现在时态："点击提交按钮发送交易"而非"点击提交按钮将发送交易"

人称使用

统一使用第二人称：

您可以通过Sui Explorer查看交易历史

文档结构规范

标题层级体系

1. 主题标题：明确包含关键词

   在Sui上部署智能合约

2. 章节标题：句子式首字母大写

   ## 配置Sui开发环境
   

列表使用场景

• 有序列表：严格按步骤执行的操作

  1. 安装Rust工具链
  1. 配置Cargo环境
  

• 无序列表：并列信息项

  - 支持Firefox最新版
  - 支持Chrome 100+
  

数字与单位规范

书写规则

• 10以下数字拼写：三个验证节点
• 10以上数字用阿拉伯数字：15笔待处理交易
• 量词组合：五个8GB内存节点

特殊情形

禁止数字开头句子：

需要至少3个验证节点 → 验证节点数量需至少3个

超链接最佳实践

内部链接

• 使用相对路径并包含.mdx扩展名
• 链接文本需反映目标标题

  详见[Sui智能合约示例](/guides/developer/examples.mdx)
  

锚点定位

配置前请确认[系统需求](/install.mdx#requirements)

操作流程编写

标准结构

1. 动名词引导的引言
2. 编号步骤列表
3. 关键操作加粗

示例：

更新Sui CLI版本：

1. 打开终端
1. 执行 **`cargo install --locked sui`**
1. 验证版本 **`sui --version`**

视觉元素规范

图表标准

• 格式优先选择PNG，次选JPG
• 最小宽度400像素
• Mermaid流程图示例：

  graph TD
    A[交易提交] --> B[验证节点]
    B --> C[共识引擎]
    C --> D[执行引擎]
  

总结

遵循Sui文档风格指南能确保技术内容具备：

• 专业统一的外观
• 清晰易懂的表达
• 良好的可访问性
• 高效的检索体验

这些规范不仅提升文档质量，更能降低开发者使用Sui生态的门槛，促进项目健康发展。

sui Sui, a next-generation smart contract platform with high throughput, low latency, and an asset-oriented programming model powered by the Move programming language 项目地址: https://gitcode.com/gh_mirrors/su/sui