技术文档写作风格 - 段落

1. 段落核心要求1.1 主题单一性规范一个段落只能有一个主题或一个中心句子。要求说明检查方法内容聚焦段落只阐述一个核心信息点删除该段后文档是否缺失某一完整信息边界清晰不与其他段落主题重叠或混杂该段内容能否用一句话概括逻辑独立段落内部逻辑自洽不依赖外部上下文单独阅读该段是否完整可懂✅ 正确示例事务日志用于记录数据库的所有修改操作确保数据可恢复。 默认存储路径为 /var/log/db当日志文件超过 1GB 时自动轮转。第一段主题事务日志的作用。第二段主题事务日志的存储规则。主题独立互不混杂。❌ 错误示例事务日志用于记录数据库的所有修改操作确保数据可恢复默认存储在 /var/log/db 目录下文件超过 1GB 时会自动轮转同时建议定期备份到远程服务器以防止本地磁盘故障。错误原因包含作用、存储规则、轮转机制、备份建议四个主题违反单一性原则。1.2 段首中心句规范段落的中心句子放在句首对全段内容进行概述。后面陈述的句子作为说明、展开、论据等为核心语句服务。要素要求示例位置固定必须是段落第一句—功能明确概括全段核心内容“连接池通过复用连接降低资源消耗。”后续服务其余句子仅作支撑说明解释原理、列举参数、提供示例✅ 正确示例连接池通过复用连接降低资源消耗。 初始化时创建固定数量的连接请求到达时直接分配空闲连接使用完毕后归还至池中。默认连接数为 10最大不超过 100。首句连接池通过复用连接降低资源消耗概括核心机制后续三句分别说明流程和参数均服务于首句。❌ 错误示例初始化时创建固定数量的连接请求到达时直接分配空闲连接使用完毕后归还至池中。连接池通过复用连接降低资源消耗默认连接数为 10。错误原因核心结论降低资源消耗被淹没在中间读者无法快速抓取段落主旨。2. 段落长度控制2.1 单段长度规范一个段落的长度不应超过 7 行最佳段落长度应小于等于 4 行。长度状态处理建议≤4 行✅ 最佳保持现状5-7 行⚠️ 可接受检查是否可精简或拆分7 行❌ 超标必须拆分优先检查主题数量2.2 连续段落数量规范连续的段落建议不超过 3 个。场景处理方式示例连续 3 个段落以上插入图表、列表或代码块打断第 3 段后插入配置表示例内容密集考虑使用表格或流程图替代将步骤描述转为流程图层级复杂使用标题分级而非段落堆砌新增三级标题分隔✅ 正确示例3.1 连接池配置 连接池通过复用连接降低资源消耗。 初始化时创建固定数量的连接请求到达时直接分配空闲连接。 [插入连接池工作原理图] 默认连接数为 10最大不超过 100。超时时间为 30 秒。两个短段 图表 一个短段视觉节奏良好信息密度适中。❌ 错误示例连接池通过复用连接降低资源消耗。初始化时创建固定数量的连接请求到达时直接分配空闲连接使用完毕后归还至池中。默认连接数为 10最大不超过 100。超时时间为 30 秒超过此时间未归还的连接将被强制回收。建议根据并发量调整参数监控活跃连接数与总连接数的比例比例超过 80% 时需扩容。错误原因连续 5 行无打断无图表辅助阅读负担重。3. 段落语言风格3.1 语气要求规范段落的句子语气要使用陈述和肯定语气避免使用感叹语气。允许语气使用场景示例陈述语气概念说明、事实描述“负载均衡分发请求至多个节点。”肯定语气操作指令、配置要求“内存必须大于 4GB。”建议语气可选优化、最佳实践“建议将超时时间设置为 30 秒。”禁止语气示例修正感叹语气“请务必注意”“注意”疑问语气“为什么要配置超时时间”“配置超时时间可防止资源阻塞。”祈使感叹“千万不要删除此文件”“禁止删除此文件。”3.2 表达方式规范对于技术描述类主题应考虑先图表、后句子的原则不要单一地使用段落来陈述主题。信息类型优先表达辅助表达流程步骤流程图关键步骤文字说明数据对比表格差异点文字强调架构关系架构图组件职责文字简述配置参数代码块/配置表参数含义文字解释状态转换状态图触发条件文字说明✅ 正确示例3.2 请求处理流程 [插入请求处理流程图] 请求依次经过接入层、业务层、数据层。每层处理超时时间为 30 秒超时时向上层返回错误码 E5001。图表展示整体流程文字补充关键参数各司其职。❌ 错误示例3.2 请求处理流程 客户端发送请求至接入层接入层进行身份验证验证通过后转发至业务层业务层执行业务逻辑如需数据则查询数据层数据层返回结果给业务层业务层处理完成后返回给接入层接入层最终返回给客户端。若任一层处理超时向上层返回错误码 E5001。错误原因纯文字描述流程信息密度低理解成本高。4. 段落间逻辑关系规范相邻段落需通过逻辑关系词建立明确联系禁止逻辑断层。关系类型关系词使用场景示例并列关系同时、此外、另外补充同类信息“同时支持 HTTPS 协议。”递进关系更进一步、不仅如此深化信息层次“更进一步支持自动故障转移。”因果关系因此、由于、基于此说明原因或结果“因此建议开启监控告警。”时序关系首先、然后、最后描述操作顺序“首先配置基础参数然后启动服务。”✅ 正确示例并列连接池默认大小为 10。此外支持动态扩容至 100。✅ 正确示例递进系统支持主从复制。更进一步支持多主架构下的双向同步。✅ 正确示例因果日志文件增长过快可能占满磁盘。因此建议配置自动清理策略。✅ 正确示例时序首先停止应用服务然后备份数据文件最后执行升级脚本。❌ 错误示例连接池默认大小为 10。动态扩容至 100。建议配置监控。错误原因三个段落间无任何逻辑关系词读者无法判断是并列、递进还是独立主题。5. 规范速查表类别核心规范检查要点主题单一性一段一主题一主题一中心句该段能否用一句话概括删除后是否缺失完整信息段首中心句首句概括全段后续仅作支撑首句是否为段落核心删除后段落是否失去主旨段落长度单段≤7行最佳≤4行连续段落≤3个是否超标是否需插入图表打断语言风格陈述肯定语气先图表后文字是否出现感叹号是否纯文字堆砌逻辑关系段落间需有明确逻辑关联词相邻段落是并列、递进、因果还是时序是否标注