authentik项目文档风格指南详解

authentik项目文档风格指南详解

authentik The authentication glue you need. 项目地址: https://gitcode.com/gh_mirrors/au/authentik

前言

在开源身份认证管理项目authentik中，良好的文档是项目成功的关键因素之一。本文旨在为authentik文档贡献者提供全面的风格指南，帮助创建一致、清晰且易于理解的文档内容。无论您是技术文档作者还是开发者，遵循这些规范都能显著提升文档质量。

文档结构与组织原则

逻辑流程设计

authentik文档应遵循用户实际操作流程组织内容：

1. 按照UI界面顺序排列操作步骤
2. 保持章节结构与用户工作流一致
3. 对于复杂流程，先提供概览再分解详细步骤

标题层级规范

采用清晰的标题层级结构：

• 主标题(H1)：文档主题
• 二级标题(H2)：主要章节
• 三级标题(H3)：子章节
• 四级标题(H4)：更细分的主题

标题应使用句子式大小写（仅首字母大写），避免全大写或标题式大小写。

术语与命名规范

产品名称处理

• 产品名称"authentik"始终小写开头，保留末尾的"k"
• 公司全称为"Authentik Security, Inc."
• 管理界面称为"Admin interface"，其中"Admin"保持大写

技术术语使用

• 使用标准技术术语如OAuth、SAML、Docker等
• 首次出现缩写时需完整拼写（如"Security Assertion Markup Language (SAML)"）
• 避免使用非通用缩写

写作风格指南

语气与表达

• 采用专业但友好的语气
• 使用第二人称（"你"）直接与读者对话
• 优先使用主动语态和现在时态

标点与格式

• 适度使用逗号，避免过度使用
• 列表项如果是完整句子需加句号
• 使用牛津逗号提高清晰度

大小写规则

• 标题采用句子式大小写
• 冒号后的内容根据上下文决定是否大写
• 专有名词保持原有大小写

用词选择技巧

常见易混淆词汇

1. "can" vs "may" vs "might":

   • 使用"can"表示能力
   • 使用"might"表示可能性
   • 避免使用"may"（易产生歧义）

2. 登录相关术语:

   • 名词："login"（如登录面板）
   • 动词："log in"（如用户需要登录）
   • 带介词："log in to"（如登录到应用）

连接词使用

• 使用"that"连接名词和动词（如"你在步骤3创建的provider"）
• "which"用于附加信息，"that"用于必要信息
• 因果关系使用"because"，时间关系使用"since"

格式规范详解

文本样式应用

• 粗体：用于UI元素和关键操作
• 斜体：强调重要概念（适度使用）
• 代码样式：命令、路径和代码片段

列表编写规范

• 统一使用完整或不完整句子
• 保持列表项语法结构一致
• 复杂列表可分层级

变量表示方法

使用尖括号表示变量：

https://authentik.company/application/o/<slug>/.well-known/openid-configuration

代码块规范

代码块需包含：

key: value
list:
  - item1
  - item2

可选参数：

• 语言类型（yaml/python/bash等）
• 显示行号
• 高亮特定行
• 添加标题说明

高级格式组件

多配置选项展示

使用标签页展示不同配置方案：

<Tabs
    defaultValue="oidc"
    values={[
        { label: "OIDC", value: "oidc" },
        { label: "SAML", value: "saml" },
    ]}
>
    <TabItem value="oidc">OIDC配置详情</TabItem>
    <TabItem value="saml">SAML配置详情</TabItem>
</Tabs>

错误信息处理

错误文档应包含：

1. 错误消息展示
2. 可能原因分析
3. 解决方案建议

示例：

• 错误消息：

  认证失败：无效凭证
  

• 可能原因：
  • 用户名或密码错误
  • 账户因多次失败尝试被锁定
• 解决方案：
  • 检查凭证
  • 必要时重置密码
  • 联系管理员解锁账户

无障碍最佳实践

1. 避免仅依赖颜色传递信息
2. 使用描述性链接文本（避免"点击这里"）
3. 为图像添加替代文本
4. 确保高对比度可读性

提示与警告格式

信息提示

:::info
这是普通提示信息
:::

重要警告

:::warning
这是需要特别注意的警告信息
:::

结语

遵循本风格指南将确保authentik文档保持专业、一致且用户友好。良好的文档能够显著降低用户的学习曲线，提升产品采用率。我们鼓励所有贡献者在提交文档变更前参考本指南，共同维护高质量的文档标准。

authentik The authentication glue you need. 项目地址: https://gitcode.com/gh_mirrors/au/authentik