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