Home Assistant 用户文档写作风格指南从品牌个性到仓库落地实践【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io导读本文档是 home-assistant.io 仓库中用于指导 Home Assistant 官方用户文档写作的风格规范原文位于 .claude/skills/home-assistant-docs-writing-style/SKILL.md。它定义了面向全球用户的文档语气、语言规则、列表与结构规范以及集成文档的标准化写作流程。读完本文你将掌握一套可直接落地的文档写作方法论并了解这些规则在本仓库中的具体实现——包括.textlintrc.json自动检查规则、集成文档模板与可复用片段。文档定位写给谁、为什么写这份风格指南解决一个核心问题Home Assistant 的用户文档面向广泛的大众读者而不是开发者。默认假设读者主要通过界面UI操作产品因此文档要让 Home Assistant 显得平易近人、稳定可靠、易于上手。由此衍生出一个贯穿全文的基本原则将 UI 操作作为标准且推荐的方式而把 YAML、模板、代码和手工编辑视为仅在特定需求下才使用的可选路径。这一原则直接体现在仓库的集成文档模板中例如 source/_integrations/_integration_docs_template.markdown 的配置章节同时提供了 UI 配置{% include integrations/config_flow.md %}与 YAML 配置两种写法但默认优先展示 UI 路径。品牌个性文档的人格指南定义了 Home Assistant 文档应呈现的五种品牌个性它们是所有写作决策的底色Welcoming欢迎在读者自身的水平上与之相遇绝不居高临下。Candid坦诚直接而诚实不用虚假的简洁或营销话术掩盖复杂性。Supportive支持以务实、耐心的方式引导读者向前。Generous慷慨给予读者所需的信息但不让其感到负担或受轻视。Independent独立自信、直接、有人情味不模仿企业科技品牌的腔调。这五种个性共同指向一个目标让文档读起来像一位懂行的朋友在耐心讲解而不是一份冷冰冰的产品说明书。受众与语气规则面向全球读者写作包括母语非英语的人因此表达必须清晰直接。使用美式英语American English并遵循Microsoft Style Guide的文档写作规范。使用包容、客观、无歧视的语言。直接以you和your称呼读者不用 the user 或 users。语气信息丰富且友好而非正式或过度技术化。避免让 Home Assistant 听起来脆弱、难用或容易出问题。不假设读者是开发者除非措辞本身是产品的一部分否则不把 YAML 配置等复杂功能标注为 advanced。通用语言规则可被 textlint 自动执行的规范指南列出了一组可机械执行的通用语言规则本仓库通过 .textlintrc.json 将其固化为自动化检查这是理解这些规则的最佳落地证据。核心规则包括使用牛津逗号Oxford comma例如 apples, oranges, and pears。遵守语法规则句子以句号结尾句号后不加两个空格。Markdown 中使用自然流动的文本不为散文强制任意换行。强调不使用全大写仅在必要时使用斜体。用加粗表示 UI 字符串不用加粗做强调或替代标题。UI 路径使用面包屑格式SettingsDevices services。始终写全称Home Assistant不使用 HA 或 HASS——这在 .textlintrc.json 中有对应替换规则[ HA , Home Assistant]、[hass, Home Assistant]、[Hass\\.?io, Home Assistant]。标题采用句子式大小写sentence-style capitalization。不用 e.g.、i.e.、etc. 或 etcetera改用 like、for example、such as。优先用 select 而不是 click除非特指鼠标动作如右键单击、双击。不使用 master/slave 这类表述改用 client/server、leader/follower、main/replica、controller/device 等替代词。匹配品牌名、服务、协议、集成和平台的官方大小写例如使用Z-Wave而非 Zwave、Z-wave 等变体——.textlintrc.json 中的[ZWave, Z-Wave]规则即为此而设。.textlintrc.json 中还维护了数百个品牌名术语白名单从 ABB、AdGuard Home 到 ZHA、Zigbee以及大量自动替换规则例如[e\\.g\\., e.g.,]、[colour, color]、[analyse, analyze]、[behaviour, behavior]、[grey, gray]、[travelled, traveled]、[cancelled, canceled]、[end ?to ?end, end-to-end]、[client ?side, client-side]。这意味着语言规范不只是建议而是提交前会被自动检查的硬性约束。列表规则清晰的组织形式列表前后用空行包围。顺序步骤、流程或按优先级排列的内容用编号列表。非顺序项或顺序无关的内容用项目符号列表。每项以大写字母开头除非有特殊原因如命令或代码块。列表项末尾不加分号、逗号或 and、or 等连词。只要列表中有任意一项是完整句子所有项末尾都要加句号如果所有项都不是完整句子则不加句号。内容结构渐进式披露页面以简短的概述或介绍开头。使用渐进式披露progressive disclosure基础信息在前复杂细节在后。较长的内容拆分为逻辑清晰的小节并配以明确的标题。优先使用列表而非表格因为表格在移动设备上往往渲染不佳。仅在有助于读者查找内容、且不损害清晰度、信任度和可读性的前提下使用 SEO、LLMO 和 GEO 技巧。当内部链接有助于读者找到相关信息时主动建立内部链接。自然融入相关的长尾词、短语和关键词。这一结构原则在 source/_integrations/_integration_docs_template.markdown 中得到完整体现页面以一句话概述开始随后按Supported devices → Prerequisites → Configuration → Configuration options → Supported functionality → Triggers/Conditions/Actions → Examples → Data updates → Known limitations → Troubleshooting → Removing the integration的顺序渐进展开。集成与平台文档标准化的写作流程这是指南中篇幅最大、最具可操作性的部分规定了集成文档的完整写作规范集成可通过 UI 配置时从 UI 路径写起。适用时使用可复用片段例如{% include integrations/config_flow.md %}。该片段在 source/_includes/integrations/config_flow.md 中定义自动生成Configuration章节优先推荐使用 My button 一键添加并给出自动发现提示Discovered以及可折叠的 Manual configuration steps 手工配置步骤。以 source/_integrations/_integration_docs_template.markdown 作为集成页面的起点模板。保持集成页面贴近模板结构Introduction、Supported devices、Unsupported devices、Prerequisites、Configuration、Configuration options、Supported functionality、Trigories/Conditions/Actions、Examples、Data updates、Known limitations、Troubleshooting、Community notes、Removing the integration。触发器、条件和动作分别写在source/_triggers、source/_conditions、source/_actions目录下的独立文件中再从集成页面通过{% include integrations/triggers.md %}、{% include integrations/conditions.md %}、{% include integrations/actions.md %}引入。这些片段的实现见 triggers.md、conditions.md、actions.md它们会自动按page.ha_domain从对应目录聚合当前集成的全部触发器等并生成链接列表。创建或大幅更新集成文档时使用document-integration-docs工具。模板中还展示了配置变量的两种文档写法UI 配置流用{% configuration_basic %}YAML 配置用{% configuration %}配置选项用{% configuration_basic %}呈现自动化示例放在{% details YAML example... %}折叠块中并用{% example %}包裹删除集成章节则通过{% include integrations/remove_device_service.md %}实现见 remove_device_service.md引用标准步骤。废弃功能与集成的处理功能被废弃或集成从 Home Assistant 移除时删除对应文档。功能废弃时删除集成页面中的相关章节。不要在文档中添加弃用通知。整个集成被废弃时遵循移除集成页面的标准步骤。其他文档规则除非被明确要求不要凭空发明新的仪表盘、卡片、自动化或脚本示例改进已有示例时仅做澄清、注释或小幅简化如删除默认值或不必要的代码。集成或平台改名时同步更新文档。重命名或移动页面时必须在_redirects中添加条目——即使内容只是移动到文档的其他位置。该文件位于仓库根目录_redirects。在source/_posts添加博客文章时authorfront matter 中的作者必须是 source/_data/people.yml 中的顶层键如果作者不存在必须先添加才能发布。这说明博客作者信息以 source/_data 目录下的 YAML 数据文件为唯一事实来源文档构建时依赖这些数据生成作者页面。小结一份可自动执行的写作规范这份风格指南的精髓在于规范可执行品牌个性与语气是方向语言与列表规则是标准而 .textlintrc.json 的术语表与替换规则、集成文档模板、以及config_flow、triggers、conditions、actions、remove_device_service等可复用片段则把规范固化到了仓库的构建流程中。任何为 Home Assistant 撰写用户文档的贡献者都可以按这份指南快速写出风格统一、结构规范、对全球读者友好的文档本文所引用的仓库文件即为这些规则的最直接实现与参照。【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Home Assistant 用户文档写作风格指南：从品牌个性到仓库落地实践
Home Assistant 用户文档写作风格指南从品牌个性到仓库落地实践【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io导读本文档是 home-assistant.io 仓库中用于指导 Home Assistant 官方用户文档写作的风格规范原文位于 .claude/skills/home-assistant-docs-writing-style/SKILL.md。它定义了面向全球用户的文档语气、语言规则、列表与结构规范以及集成文档的标准化写作流程。读完本文你将掌握一套可直接落地的文档写作方法论并了解这些规则在本仓库中的具体实现——包括.textlintrc.json自动检查规则、集成文档模板与可复用片段。文档定位写给谁、为什么写这份风格指南解决一个核心问题Home Assistant 的用户文档面向广泛的大众读者而不是开发者。默认假设读者主要通过界面UI操作产品因此文档要让 Home Assistant 显得平易近人、稳定可靠、易于上手。由此衍生出一个贯穿全文的基本原则将 UI 操作作为标准且推荐的方式而把 YAML、模板、代码和手工编辑视为仅在特定需求下才使用的可选路径。这一原则直接体现在仓库的集成文档模板中例如 source/_integrations/_integration_docs_template.markdown 的配置章节同时提供了 UI 配置{% include integrations/config_flow.md %}与 YAML 配置两种写法但默认优先展示 UI 路径。品牌个性文档的人格指南定义了 Home Assistant 文档应呈现的五种品牌个性它们是所有写作决策的底色Welcoming欢迎在读者自身的水平上与之相遇绝不居高临下。Candid坦诚直接而诚实不用虚假的简洁或营销话术掩盖复杂性。Supportive支持以务实、耐心的方式引导读者向前。Generous慷慨给予读者所需的信息但不让其感到负担或受轻视。Independent独立自信、直接、有人情味不模仿企业科技品牌的腔调。这五种个性共同指向一个目标让文档读起来像一位懂行的朋友在耐心讲解而不是一份冷冰冰的产品说明书。受众与语气规则面向全球读者写作包括母语非英语的人因此表达必须清晰直接。使用美式英语American English并遵循Microsoft Style Guide的文档写作规范。使用包容、客观、无歧视的语言。直接以you和your称呼读者不用 the user 或 users。语气信息丰富且友好而非正式或过度技术化。避免让 Home Assistant 听起来脆弱、难用或容易出问题。不假设读者是开发者除非措辞本身是产品的一部分否则不把 YAML 配置等复杂功能标注为 advanced。通用语言规则可被 textlint 自动执行的规范指南列出了一组可机械执行的通用语言规则本仓库通过 .textlintrc.json 将其固化为自动化检查这是理解这些规则的最佳落地证据。核心规则包括使用牛津逗号Oxford comma例如 apples, oranges, and pears。遵守语法规则句子以句号结尾句号后不加两个空格。Markdown 中使用自然流动的文本不为散文强制任意换行。强调不使用全大写仅在必要时使用斜体。用加粗表示 UI 字符串不用加粗做强调或替代标题。UI 路径使用面包屑格式SettingsDevices services。始终写全称Home Assistant不使用 HA 或 HASS——这在 .textlintrc.json 中有对应替换规则[ HA , Home Assistant]、[hass, Home Assistant]、[Hass\\.?io, Home Assistant]。标题采用句子式大小写sentence-style capitalization。不用 e.g.、i.e.、etc. 或 etcetera改用 like、for example、such as。优先用 select 而不是 click除非特指鼠标动作如右键单击、双击。不使用 master/slave 这类表述改用 client/server、leader/follower、main/replica、controller/device 等替代词。匹配品牌名、服务、协议、集成和平台的官方大小写例如使用Z-Wave而非 Zwave、Z-wave 等变体——.textlintrc.json 中的[ZWave, Z-Wave]规则即为此而设。.textlintrc.json 中还维护了数百个品牌名术语白名单从 ABB、AdGuard Home 到 ZHA、Zigbee以及大量自动替换规则例如[e\\.g\\., e.g.,]、[colour, color]、[analyse, analyze]、[behaviour, behavior]、[grey, gray]、[travelled, traveled]、[cancelled, canceled]、[end ?to ?end, end-to-end]、[client ?side, client-side]。这意味着语言规范不只是建议而是提交前会被自动检查的硬性约束。列表规则清晰的组织形式列表前后用空行包围。顺序步骤、流程或按优先级排列的内容用编号列表。非顺序项或顺序无关的内容用项目符号列表。每项以大写字母开头除非有特殊原因如命令或代码块。列表项末尾不加分号、逗号或 and、or 等连词。只要列表中有任意一项是完整句子所有项末尾都要加句号如果所有项都不是完整句子则不加句号。内容结构渐进式披露页面以简短的概述或介绍开头。使用渐进式披露progressive disclosure基础信息在前复杂细节在后。较长的内容拆分为逻辑清晰的小节并配以明确的标题。优先使用列表而非表格因为表格在移动设备上往往渲染不佳。仅在有助于读者查找内容、且不损害清晰度、信任度和可读性的前提下使用 SEO、LLMO 和 GEO 技巧。当内部链接有助于读者找到相关信息时主动建立内部链接。自然融入相关的长尾词、短语和关键词。这一结构原则在 source/_integrations/_integration_docs_template.markdown 中得到完整体现页面以一句话概述开始随后按Supported devices → Prerequisites → Configuration → Configuration options → Supported functionality → Triggers/Conditions/Actions → Examples → Data updates → Known limitations → Troubleshooting → Removing the integration的顺序渐进展开。集成与平台文档标准化的写作流程这是指南中篇幅最大、最具可操作性的部分规定了集成文档的完整写作规范集成可通过 UI 配置时从 UI 路径写起。适用时使用可复用片段例如{% include integrations/config_flow.md %}。该片段在 source/_includes/integrations/config_flow.md 中定义自动生成Configuration章节优先推荐使用 My button 一键添加并给出自动发现提示Discovered以及可折叠的 Manual configuration steps 手工配置步骤。以 source/_integrations/_integration_docs_template.markdown 作为集成页面的起点模板。保持集成页面贴近模板结构Introduction、Supported devices、Unsupported devices、Prerequisites、Configuration、Configuration options、Supported functionality、Trigories/Conditions/Actions、Examples、Data updates、Known limitations、Troubleshooting、Community notes、Removing the integration。触发器、条件和动作分别写在source/_triggers、source/_conditions、source/_actions目录下的独立文件中再从集成页面通过{% include integrations/triggers.md %}、{% include integrations/conditions.md %}、{% include integrations/actions.md %}引入。这些片段的实现见 triggers.md、conditions.md、actions.md它们会自动按page.ha_domain从对应目录聚合当前集成的全部触发器等并生成链接列表。创建或大幅更新集成文档时使用document-integration-docs工具。模板中还展示了配置变量的两种文档写法UI 配置流用{% configuration_basic %}YAML 配置用{% configuration %}配置选项用{% configuration_basic %}呈现自动化示例放在{% details YAML example... %}折叠块中并用{% example %}包裹删除集成章节则通过{% include integrations/remove_device_service.md %}实现见 remove_device_service.md引用标准步骤。废弃功能与集成的处理功能被废弃或集成从 Home Assistant 移除时删除对应文档。功能废弃时删除集成页面中的相关章节。不要在文档中添加弃用通知。整个集成被废弃时遵循移除集成页面的标准步骤。其他文档规则除非被明确要求不要凭空发明新的仪表盘、卡片、自动化或脚本示例改进已有示例时仅做澄清、注释或小幅简化如删除默认值或不必要的代码。集成或平台改名时同步更新文档。重命名或移动页面时必须在_redirects中添加条目——即使内容只是移动到文档的其他位置。该文件位于仓库根目录_redirects。在source/_posts添加博客文章时authorfront matter 中的作者必须是 source/_data/people.yml 中的顶层键如果作者不存在必须先添加才能发布。这说明博客作者信息以 source/_data 目录下的 YAML 数据文件为唯一事实来源文档构建时依赖这些数据生成作者页面。小结一份可自动执行的写作规范这份风格指南的精髓在于规范可执行品牌个性与语气是方向语言与列表规则是标准而 .textlintrc.json 的术语表与替换规则、集成文档模板、以及config_flow、triggers、conditions、actions、remove_device_service等可复用片段则把规范固化到了仓库的构建流程中。任何为 Home Assistant 撰写用户文档的贡献者都可以按这份指南快速写出风格统一、结构规范、对全球读者友好的文档本文所引用的仓库文件即为这些规则的最直接实现与参照。【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
