Unraid 文档样式指南
Unraid OS 是由 LimeTech 团队和 Unraid 社区共同塑造的。我们的文档旨在做到全面、准确和最新。由于我们的用户来自全球各地，本指南为统一、清晰地撰写 Unraid 文档奠定基础。
写作惯例
风格和语气
我们的语气在友好和正式之间取得平衡，旨在为用户提供详细准确且有亲和力的内容。
- 在操作固定且没有偏差余地时，使用正式直接的指令。
- 在提供上下文或场景时，使用对话性、解释性的语气，使内容更易接近。
作为贡献者，选择语气时要考虑上下文和受众。
由于 Unraid OS 拥有全球用户，我们避免使用专业术语、俚语或成语。这些可能会让非英语母语者感到困惑，并加大翻译过程的复杂性。
目标受众：为所有水平的读者写作
我们的读者从了解系统内部的 Linux 专家到初次使用 Unraid 的新手都有。
以清晰和包容的方式书写，以便专家和新手都能顺畅地跟随。
ABC 方法：准确、简洁、 清晰
我们优先考虑：
- 准确性：确保内容正确并经过彻底测试。
- 简洁性：在不牺牲必要细节的前提下简明扼要。
- 清晰性：使用简单的语言和结构来保证内容易于理解。
语法结构
Unraid 文档结合使用 Markdown 格式和特定文本样式，帮助用户快速识别界面元素并导航 WebGUI。
| 元素类型 | 样式惯例 | Markdown 语法 | 示例 / 描述 |
|---|---|---|---|
| 选项或按钮名称 | 粗体 | **text** | 选择 完成 |
| 用户输入值 | 斜体 | *text* | 输入值 50gb |
| 导航路径 | 粗体 + 斜体；使用 → | ***nav1 → nav2*** | 设置 → 磁盘设置 |
| 选项卡标签 | 粗体 | 标签名称 | 要选择的选项卡名称 |
| 复选框标签 | 粗体 | 复选框标签 | 复选框选项的标签 |
| 下拉菜单选项 | 斜体 | 下拉选项 | 下拉菜单中的可选选项 |
| 对话框标题 | 三级标题 | ### Dialog Title | 弹出对话框或模态窗口的标题 |
| 工具提示文本 | 内联斜体 | tooltip text | 悬停时显示的简短说明 |
| 菜单项 | 粗体 + 斜体 | 菜单 → 子菜单 → 项目 | 通过嵌套菜单进行导航 |
| CLI 和系统输出 | 等宽字体（内联代码） | `text` | 导航到 http://tower.local |
| 错误消息 | 等宽字体（内联代码） | `错误：消息` | 精确的错误字符串或日志 |
| 文档标题 | 一级标题 | # 标题 | （渲染为）<h1>标题</h1> |
| 文档部分 | 二级标题 | ## 标题 | （渲染为）<h2>标题</h2> |
| 文档子章节 | 三级标题 | ### 标题 | （渲染为）<h3>标题</h3> |
每一个二级标题（##）及更小的标题都显示在页面目录（TOC）侧边栏中，便于导航。
列表和表格格式化
有效使用结构化元素（如列表和表格）能改善信息清晰度，帮助理解，并支持快速参考。
列表
列表帮助用户吸收、回忆和遵循关键要点或步骤。主要有两种类型，各有明确的用例：
-
无序列表（符号）：用于分组相关项目，而不暗示顺序。 例子： “常见的 Unraid OS 工具列表。”
-
有序列表（编号）：用于显示必要的顺序或过程。 例子： “要启动 array...”
- 尝试用一个以冒号结尾的清晰提示句引导列表。
- 在无序列表中使用 4-6 个项目的最大方便扫描和记忆。更长的列表可能作为表格更好。
表格
表格是通过将信息分组为行和列来组织相关数据的好方法，从而使比较更快更精确。
- 对于需要并排比较的多个相关数据点，使用表格。
- 避免使用仅有 1 或 2 个单元的表格；改用符号列表或句子。
- 用一个说明其目的和内容的句子来引入表格。
缩写、首字母缩写和简称
为了减少读者的混淆，请遵循这些关于缩写的原则：
- 缩写是单词的缩短形式，通常在 Unraid 文档中不必要，除非它们是普遍认可的。
- 首字母缩写词通过其他词的首字母创建新词（例如，RAID）。
- 简称使用首字母并分别发音（例如，OS，ZFS）。
建议：
- 优先使用现有的、熟知的首字母缩写词或简称，读者熟悉的。
- 避免仅为简洁而创建新缩写。
- 首次使用不常见的首字母缩写词或简称时，务必拼出完整形式，并在后面加括号注明缩写。 例子： 虚拟机磁盘 (VMDK)
链接到其他文件或网站
战略性链接允许读者探索相关主题并增强他们的理解。使用这些指南来实现实用且可访问的超链接。
链接文本指南
- 链接文本应清楚地描述目的地，帮助所有读者掌握链接的用途。
- 避免使用诸如“点击此处”或“阅读更多”之类的模糊链接文本，因为这些缺乏上下文。
- 避免使用原始 URL 作为内联链接文本。
链接格式化
- 使用内联 Markdown 链接：
You can also check our [getting started guide](../unraid-os/getting-started/quick-start-guide.mdx).
- 始终链接到最相关的权威资源。
添加术语表术语
Unraid 文档利用了集中的术语表系统，以确保技术术语的一致性和可访问性。术语表条目保存在根目录的 glossary.yaml 文件中。
添加或更新术语：
- 使用以下模板编辑
glossary.yaml：
GlossaryTerm:
term: Display Name
def: Full definition text.
link: <a href="https://example.com">Optional detailed link</a>
-
要添加工具提示功能，请在文档中使用以下语法引用术语：
%%Term|GlossaryTerm%%……管道左侧为希望显示的文本，右侧为 YAML 文件中的相应术语条目。
-
- 术语表页面将自动更新以包含新术语。