软件技术文档黄金法则：清晰、准确、简洁的写作指南

CodeGeek橘子
0 阅读8分钟

一、引言

在软件领域，一份优质的技术文档对于软件的开发、使用和维护都起着至关重要的作用。它不仅是开发者之间沟通的桥梁，也是用户了解和使用软件的重要依据。本文将参考链接中的内容，为你提供软件相关技术文档的写作指导。

二、写作规范要点

（一）标题

  1. 层级 - 标题分为四级，一级标题为文章标题，二级标题是文章主要部分大标题，三级标题是二级标题下小标题，四级标题是三级标题下某方面小标题。示例如下：
# 一级标题
## 二级标题
### 三级标题
#### 四级标题

- 一级标题下不能直接出现三级标题，要避免孤立编号，下级标题不重复上一级标题名字，谨慎使用四级标题，尽量避免出现以保持层级简单。
  1. 原则 - 例如，以下结构缺少二级标题：
# 一级标题
### 三级标题

- 若二级标题只包含一个三级标题，可省略三级标题，如：

## 二级标题 A
### 三级标题 A
## 二级标题 B

- 避免二级标题与下属三级标题同名，如：

## 概述
### 概述

（二）文本

  1. 字间距

    • 全角中文字符与半角英文字符间应有半角空格，如“本文介绍如何快速启动 Windows 系统”。
    • 全角中文字符与半角阿拉伯数字间有无半角空格均可，但风格要统一，半角百分号视同阿拉伯数字，如“今年我国经济增长率是 6.5%”。
    • 英文单位若不翻译，单位前阿拉伯数字与单位符号间应留空隙，如“一部容量为 16 GB 的智能手机”。
    • 半角英文字符和半角阿拉伯数字与全角标点符号间不留空格，如“他的电脑是 MacBook Air”。

  2. 句子 - 避免长句，单个句子或逗号分隔的句子构件长度尽量保持在 20 字以内，20 - 29 字句子可接受，30 - 39 字句子语义须明确，多于 40 字句子不能接受，逗号分割长句总长度不超 100 字或正文 3 行。例如：

错误：本产品适用于从由一台服务器进行动作控制的单一节点结构到由多台服务器进行动作控制的并行处理程序结构等多种体系结构。
正确：本产品适用于多种体系结构。无论是由一台服务器（单一节点结构），还是由多台服务器（并行处理结构）进行动作控制，均可以使用本产品。

- 尽量用简单句和并列句，避免复合句；用肯定句表达，避免否定句和双重否定句。

  1. 写作风格 - 尽量用主动语态，不用被动语态，如“假如尚未安装这个软件”。 - 不使用非正式语言风格，用现代汉语常用表达方式，用对“的”“地”“得”，使用代词时明确指代内容，名词前不过多使用形容词。

  2. 英文处理 - 英文原文复数形式翻译中文时还原为单数形式，外文缩写可用半角圆点表示，英文省略号改中文省略号，英文书名或电影名改中文时双引号改书名号。 - 第一次出现英文词汇时括号中给出中文标注，此后用英文缩写，专有名词中每个词首字母大写，非专有名词不大写。

（三）段落

  1. 原则
    • 一个段落只有一个主题或中心句子，中心句子放段首概述全段内容，后面句子为其服务。
    • 段落长度不超七行，最佳长度小于等于四行，句子语气用陈述和肯定语气，段落间用空行隔开，开头不留空白字符。
  2. 引用
    • 引用第三方内容注明出处，全篇转载在全文开头显著位置注明作者和出处并链接至原文，使用外部图片在图片下方或文末标明来源。

（四）数值

  1. 半角数字 - 阿拉伯数字用半角形式，如“这件商品的价格是 1000 元”。
  2. 千分号 - 数值千位以上添加千分号（半角逗号），4 位数值千分号可选，4 位以上应添加。
  3. 货币 - 货币用阿拉伯数字，数字前写货币符号或数字后写货币中文名称，英文货币名称参考国际标准 ISO 4217。
  4. 数值范围 - 用波浪线或一字线连接，带单位或百分号时两个数字都加单位或百分号，如“132 kg～234 kg”“67%～89%”。
  5. 变化程度表示法 - 数字增加用“增加了”“增加到”，减少用“降低了”“降低到”，不用“降低 N 倍”或“减少 N 倍”，用“降低百分之几”或“减少百分之几”。

（五）标点符号

  1. 原则 - 中文语句标点用全角符号，整句英文用英文/半角标点，句号、问号、叹号、逗号、顿号、分号和冒号不出现在一行之首，点号不出现在标题末尾，标号可以。
  2. 各类标点使用规则
    • 句号：中文语句结尾用全角句号，句子末尾括号加注时句号在括号外。
    • 逗号：表示句子内部一般性停顿，避免“一逗到底”。
    • 顿号：句子内部并列词用全角顿号分隔，英文句子并列词语用半角逗号分隔，中文句子内部并列词最后一个尽量用“和”连接。
    • 分号：表示复句内部并列分句之间的停顿。
    • 引号：引用用全角双引号，引号里再用引号时，外面双引号，里面单引号。
    • 括号：补充说明用全角圆括号，括号前后不加空格，介绍几种括号中英文名称。
    • 冒号：全角冒号用在需解释词语后引出解释说明，表示时间用半角冒号。
    • 省略号：表示语句未完或语气不连续，占两个汉字空间、含六个省略点，不与“等”字一起使用。
    • 感叹号：尽量避免使用，不得多个感叹号连用。
    • 破折号：用于进一步解释，占两个汉字位置，若只占一个汉字位置，前后留半角空格。
    • 连接号：连接两个类似的词，两个名词复合、图表编号用直线连接号，数值范围用波浪连接号或一字号，波浪连接号可用“至”代替。

（六）文档体系

  1. 结构

    • 软件手册建议采用以下结构：

      • 简介（Introduction） ：必备，提供产品和文档总体扼要说明。
      • 快速上手（Getting Started） ：可选，介绍如何快速使用产品。
      • 入门篇（Basics） ：必备，提供初级使用教程，包括环境准备、安装、设置等。
      • 进阶篇（Advanced） ：可选，提供中高级开发教程，包括 API 介绍、FAQ 等。
      • 附录（Appendix） ：可选，包含名词解释、最佳实践、故障处理、版本说明、反馈方式等内容。

    • 可参考 Redux 手册、Atom 手册。

  2. 文件名 - 文件名不含空格，用半角字符，不用全角字符和中文，建议用小写字母，某些说明文件文件名可用大写字母，文件名包含多个单词时用半角连词线分隔。

三、参考链接

四、总结

遵循上述写作规范，能够使软件技术文档更加清晰、准确、易读，提高文档的质量和实用性。在实际写作过程中，还应根据具体情况进行灵活运用，不断积累经验，提升写作水平。

avatar
文章
阅读
粉丝