配置页面展示配置密集型功能的具体设置、取值和选项,让读者能为自己的用例复制正确的设置,而不是跟随一套程序。配置也称为使用场景,属于参考页面,而不是操作说明。语气为朴实、描述性、直截了当。
当某功能高度依赖配置(例如规则),且读者主要需要知道哪些设置和取值会产生给定结果时,请编写配置页面。它不是:
- 如何操作。 如何操作带领读者完成任务的步骤,而配置只展示某一设置的设置项和取值,不含程序性步骤。
- 教程。 教程通过引导式项目教学,而配置是读者查阅正确取值的参考,不是一堂课。
- 参考。 参考会穷尽记录每个参数,而配置为常见用例精选示例设置。
完整比较请参阅内容类型。
- 标题:基于名词,点出正在配置的功能,因为配置描述的是如何设置某功能,而不是引导读者达成某个目标。
- 描述:点出所配置的产品或功能、服务的用例,以及涵盖的关键设置或取值。
复制此骨架并按你的功能进行改写:
---
title: <Feature> configuration
description: Configure <product or feature> for <use case>, covering <the key settings and values>.
pcx_content_type: configuration
sidebar:
order: 10
products:
- product-a
---
用两三句话介绍该功能,说明读者将遇到哪些配置,并链接到相关文档。
## <Feature area>
说明此配置产生的结果,然后用表格给出设置和取值。
| Setting | Value | Notes |
| -------------- | -------------------------- | ---------------- |
| <setting name> | <value to enter or select> | <when to use it> |- 表格是标志性组件:参考表中,读者可更改的每一项设置与为给定用例应输入或选择的取值一一对应。
- 当某功能有许多配置时,导航帮助读者找到正确的配置。
- 不适合放入的内容: 分步程序。如果发现自己在写操作说明,请改用如何操作、教程或示例。
pcx_content_type: configuration
products:
- product-a
- product-b欲了解更多详情,请参考 pcx_content_type。
每个配置都在标题后用简短的上下文段落开篇,介绍该功能、说明读者将遇到哪些配置,并链接到相关文档。正文按功能分组,每个功能使用自己的设置表,以便读者扫视到匹配其用例的设置。
- 完整的设置-取值对。 每行表格都给出明确的设置以及应输入或选择的精确取值,因为智能体会直接应用这对值,没有推断空间。
- 用用例框定。 在上下文中说明每种配置产生的结果,以便读者或智能体无需阅读程序即可把目标匹配到正确的表格。
- 操作说明指向外部。 将任何步骤链接到承载它们的如何操作、教程或示例,因为配置本身不能作为程序执行。