跳到主要内容

技术文档风格指南

本风格指南旨在提供创建有效且用户友好的 WooCommerce 技术文档的指导方针，这些文档将存储在代码仓库中，并由开源贡献者和 WooCommerce 团队进行编辑和迭代。

写作风格​

语言风格​

  • 重要的是使用清晰简洁的语言，使其易于理解。 使用主动语态，避免使用可能让用户不熟悉的行话或技术术语。 语气应友好且平易近人，并鼓励用户采取行动。

  • 文章采用第三人称。 示例：“将一个嵌入块添加到您的网页中。”

  • 使用美式英语的拼写和标点符号，或者考虑使用在其他英语变体中没有不同拼写的其他单词。

  • 对于文档标题和副标题，使用句首字母大写（而不是全部字母大写）。 示例：“Introduction to the launch experience” 而不是 “Introduction to the Launch Experience”。

  • 当引用文件或目录时，文本格式可以消除包含冠词（如“the”）或澄清名词（如“file”或“directory”）的必要性。 示例：“存储在 ~/wp-content/uploads/ 目录中的文件” 或 “使用 ~/config/config.yml 文件”。

写作技巧​

  • 我们的目标受众具有各种角色和能力。 在创建教程或操作指南时，重要的是要考虑目标受众。 他们是初学者还是高级用户？ 他们的技术背景是什么？ 了解受众可以帮助指导指南的详细程度和使用的语言。

  • 使用即使是那些技术知识有限的读者以及母语不是英语的读者也能理解的语言。

  • 考虑这可能是读者看到的第一个 WooCommerce 文档页面。 他们可能通过 Google 搜索或其他网站来到这里。 为读者提供足够的关于该主题的背景信息，并尽可能将单词和短语链接到其他相关的文档文章。

  • 考虑添加注释和部分，提供见解、技巧或警告信息，以扩展主题，并提供与读者相关的背景信息。

  • 当提供具体的指导、最佳实践或要求时，我们建议包括对未遵循提供的指导可能产生的潜在后果或影响的描述。 这可以帮助在文档中添加额外的搜索关键词，并在支持人员链接到文档时提供更好的上下文。

  • 始终首先为该主题编写一个概念性的、高级别的介绍，放在任何 H2 副标题之上。

教程​

教程是全面的，旨在教授新的技能或概念。

您是老师，您负责学生的学习内容。 在您的指导下，学生将执行一系列操作以达到某个目标。

Divio Framework 上的教程撰写指南

实用指南​

实用指南是专注于特定主题，提供关于如何完成特定任务或解决特定问题的说明。

实用指南与教程完全不同，切勿混淆：

  • 教程是您认为初学者需要了解的内容。
  • 实用指南是针对只有具有一定经验的用户才能提出的问题的答案。

Divio Framework 上的实用指南撰写指南

自定义代码检查规则​

在 WooCommerce，我们致力于维护技术文档的一致性和高质量标准。 我们的文档主要遵循 markdownlint 提供的代码检查规则。 为了帮助我们的贡献者，我们详细介绍了我们的自定义配置和例外情况，如下所示。

注意：虽然我们上面列出了具体的规则，但所有其他默认的代码检查规则都来自 markdownlint，除非另有说明。 我们在此处仅强调自定义配置或例外情况。 要获取 markdownlint 规则的完整列表，您可以参考 此链接。

  1. 标题样式:

    • 使用 ATX 样式 (#) 来表示标题。
      # 这是一个 H1 标题
      ## 这是一个 H2 标题

    参考: MD003

  2. 列表缩进:

    • 使用 4 个空格来缩进列表项目。
      - 项目 1
          - 子项目 1.1

    参考: MD007

  3. 行长度:

    • 对行长度没有具体的限制，但请确保段落和句子易于阅读。

    参考: MD013

  4. 内容相同的多个标题:

    • 只要它们不是兄弟标题，允许存在内容相同的多个标题。

    参考: MD024

  5. 内联 HTML:

    • 仅允许使用 video 元素时使用内联 HTML。
    <video src="path_to_video.mp4" controls></video>

    参考: MD033

  6. 制表符和空格:

    • 我们对使用硬制表符和尾随空格持开放态度。 但是，为了保持一致性，我们建议使用空格代替制表符，并避免尾随空格。

    参考: no-hard-tabs & whitespace

格式​

视觉风格​

  • 使用 H2 样式作为主要标题，以便在文章的目录中进行程序化列出。
  • 文件名和目录路径应按照 HTML 规范 的规定进行代码化处理。 示例：/wp-content/uploads/
  • 对单个目录的引用应在名称后添加尾随斜杠 (例如，添加 "/" )。 示例：“uploads/”
  • 对代码仓库的引用应不包含前导斜杠，并且不应进行任何格式化。在文章内容中首次出现代码仓库时，应尽可能链接到代码仓库的 URL。 示例：“woocommerce-blocks”，后跟“woocommerce-blocks”
  • 对函数和命令行操作的引用应以“内联代码”格式进行格式化。 示例：“使用 dig 命令获取 DNS 信息。”
  • 函数应使用“内联代码”格式进行样式设置，并保留其原始来源确定的大小写格式。 示例：WP_Query (而不是 WP_query)

视觉辅助​

视觉辅助工具，例如屏幕截图、图表、代码片段和视频，对于操作指南非常有用。 它们提供了一种视觉参考，可以帮助用户更轻松地理解说明。 在包含视觉辅助工具时，请务必清楚地对其进行标记，并提供标题或描述，以解释正在显示的内容。

缩写​

可以使用更常以缩写形式出现的短语。 首次在任何 页面 上出现缩写时，必须包含完整的短语，后跟括号中的缩写。

示例：我们通过引入高性能订单存储 (HPOS) 增强了 WooCommerce 的查询功能。

之后，可以在整个 页面 中使用缩写。

在决定一个术语是否常用时，请考虑其对 翻译 和未来国际化 (i18n) 工作的潜在影响。

模式​

文章内容​

在创建操作指南时，重要的是使用一致且易于遵循的格式。 以下是一个软件操作指南的建议模板：

简介: 概述指南所涵盖的任务或功能。

前置条件: 列出完成任务或使用功能所需的任何 前置条件。

分步说明: 提供完成任务或使用功能的详细、分步说明。 使用编号的步骤，并在适当的情况下包含屏幕截图或其他视觉辅助工具。

故障排除: 包含一个 故障排除 部分，以解决用户可能遇到的常见问题或 错误。

结论: 总结指南中的关键点，并提供任何可能有所帮助的附加 资源 或参考资料。

术语表​

组件和功能参考​

  • 首次在文章中出现时，应完整呈现 "WordPress 管理员仪表盘"，之后用缩写形式 ("WP Admin")。 之后，可以在同一篇文章中，对于任何对 WordPress 管理员仪表盘的引用，都可以使用缩写形式。
  • 引用 WordPress 管理员仪表盘的 URL 时，可以使用缩写形式 wp-admin。

测试​

在发布教程或指南之前，重要的是对其进行彻底的测试，以确保说明准确且易于理解。

结构​

拆分文档​

如果文章涵盖了太多主题，可能会让用户难以找到他们想要的信息。"拆分文档" 指的是将内容过多的文章分解为一组较小的相关文章。 这组文章通常有一个主 "仪表盘"，提供对该组文章的概述，描述性文本提供指向相关文章的链接，这些文章对用户来说可能很有用。 这些文章组可以被视为由较小、拆分的文章组成的 "信息" 单元。

将较小的内容块拆分为独立的文章，可以更容易地链接到特定主题，而不是依赖于链接到更广泛的文章，这些文章可能包含锚点。 这种更具体的链接方法对我们的支持团队很有帮助，但对于在整个文档站点上交叉链接文章也很有用。