技术文档的写作规范
技术文档的写作规范
前言
迫于自己文档写的一般，抽时间写一个总结，学习优秀文档编写经验
个人实战总结
- 参照标准文档编写。
- 编写完重读一遍，看看结构是否合理。
- 学会精炼语言，减少废话。
- 考虑阅读者是谁来决定怎么写
- 文档可以分为四个部分考量，术语规范；问题描述；客户需求；详尽描述。
标题
标题分为四级。
- 一级标题：文章的标题
- 二级标题：文章主要部分的大标题
- 三级标题：二级标题下面一级的小标题
- 四级标题：三级标题下面某一方面的小标题
文本
字间距
（1）全角中文字符与半角英文字符之间，应有一个半角空格。
（2）全角中文字符与半角阿拉伯数字之间，有没有半角空格都可，但必须保证风格统一，不能两种风格混杂。
（3）半角的百分号，视同阿拉伯数字。
（4）半角英文字符和半角阿拉伯数字，与全角标点符号之间不留空格。
句子
（1）避免使用长句。
（2）尽量使用简单句和并列句，避免使用复合句。
（3）同样一个意思，尽量使用肯定句表达，不使用否定句表达。
风格
（1）尽量不使用被动语态，改为使用主动语态。
（2）不使用非正式的语言风格。
（3）不使用冷僻、生造或者文言文的词语，而要使用现代汉语的常用表达方式。
（4）名词前不要使用过多的形容词。
英文
（1）外文缩写可以使用半角圆点(.)表示缩写。
（2）外文缩写可以使用半角圆点(.)表示缩写。
（3）表示中文时，英文省略号（...）应改为中文省略号（⋯⋯）。
（4）英文书名或电影名改用中文表达时，双引号应改为书名号。
（5）第一次出现英文词汇时，在括号中给出中文标注。此后再次出现时，直接使用英文缩写即可。
（6）专有名词中每个词第一个字母均应大写，非专有名词则不需要大写。
段落
原则
（1）一个段落只能有一个主题，或一个中心句子。
（2）段落的中心句子放在段首，对全段内容进行概述。后面陈述的句子为核心句服务。
（3）一个段落的长度不能超过七行，最佳段落长度小于等于四行。
（4）段落之间使用一个空行隔开。
（5）段落开头不要留出空白字符。
引用
引用第三方内容时，应注明出处。
标点符号
原则
- 中文语句的标点符号，均应该采取全角符号，这样可以保证视觉的一致。
- 如果整句为英文，则该句使用英文/半角标点。
- 句号、问号、叹号、逗号、顿号、分号和冒号不得出现在一行之首。
- 应该使用平静的语气叙述，尽量避免使用感叹号
！。
书籍
写作逻辑很重要，推荐一些书籍。
- 《魏斯曼演讲圣经》
- 《金字塔结构》
- 《写给大家看的设计书》