文档规范

文档目录

调整目的

用户带着待做需求找到参考的任务指南，了解天舟云的解决方案过程。逐步展开解决方案中涉及的天舟云功能组件的使用，如 单选搜索、数据字典、流程、权限等等。

✨ 快速开始 (立即吸引，获得成就感)

📖 核心概念 (用时再查，非必读)

🛠️ 任务指南 (核心入口，按用户想做的事分类)

🧩 功能详细 (所有功能的详细参考，现有文档功能部分)

⚙️ 二开定制参考 (给开发者深挖用)

🚀 解决方案 (抄作业的地方)

🐛 排查与问答 (救命的地方)

天舟云平台文档编写与维护规范 V1.0

一、 文档撰写格式规范

1.3 标题

• 采用 # 进行分级，限制在 H1 至 H4 (####)。
• H1用于文章主标题，H2/H3/H4用于文内章节。

1.4 内容元素格式

• UI元素：使用加粗。例：点击保存按钮。
• 用户输入/代码：使用行内代码样式。例：输入 SELECT * FROM table。
• 代码块：使用`包裹，并指定语言以获得高亮。

  ```javascript
  // 这是一个示例
  function helloWorld() {
    console.log('Hello, World!');
  }
  ```

• 路径：使用 > 符号表示导航路径。例：打开设置 > 项目设置 > 权限。
• 提示与警告：使用统一的表情符号和样式。
  • > 💡 **提示：** 这是一个最佳实践建议。
  • > ⚠️ **注意：** 此操作不可逆，请谨慎执行。
  • > 🚨 **警告：** 此配置可能导致系统故障。

1.5 图片与截图

• 要求：必须清晰、最新，与当前平台UI一致。
• 标注：图中需用红色方框、箭头或序号高亮关键区域。

1.6 链接

• 内部链接：使用相对路径链接到其他文档。[链接文本](../path/to/file.md)
• 外部链接：明确链接去向。[天舟云官网](https://www.tianzhouyun.com)。

二、 内容与写作风格规范

2.1 语言风格

• 用户视角：以“您”为主语，采用引导式、任务式语言。
  • 差: “该功能可以被用于设置参数。”
  • 优: “您可以通过此功能设置参数。”
• 简洁直接：使用主动语态和短句，避免复杂从句和冗长描述。
• 一致术语：严格遵循并维护平台的术语表（如统一使用“数据模型”而非“数据表”）。

2.2 内容结构
每篇指南类文档应遵循以下逻辑结构：

1. 概述：本文目标、适用场景、用户获益。
2. 前置条件：执行本文操作前必须满足的条件（权限、知识、已完成步骤）。
3. 操作步骤：使用编号列表，一步一步引导用户。
4. 示例：提供可照抄的配置或代码示例。
5. 总结/下一步：回顾要点，并推荐相关阅读内容。

三、 文档更新与维护规范

3.2 版本控制与标记

• 版本标记：在文中明确标注功能适用的版本。
  • > ✅ **v2.5.0 新增** （用于新功能）
  • > 🗑️ **自 v2.5.0 起废弃** （用于旧功能，需指明替代方案）
• 更新日志：每篇文档末尾必须包含更新历史表。

3.3 不定期检查

• 周期：不定期进行文档抽样。
• 内容：
  • 链接有效性检查。
  • 截图与最新UI一致性检查。
  • 根据用户反馈（“本文是否有用？”）优化低分文档。

通过严格执行此规范，可以确保天舟云文档始终保持高质量、高一致性和高时效性，成为用户信赖的权威参考资料。