编写项目文档
技术性写作的７条规则
-
分两步编写: 先聚焦于思想，然后审查和修整文档
- 先关注内容然后才是风格和清晰性
-
以读者为目标：谁将读这个文档？
- 在开始编写之前，要了解面向的读者
-
使用简单的风格：保持简单明了，使用良好的语法．
- 使用简单的句子，句子不用改长于两行
- 每个段落应该由３～４个句子组成，最多表达一个主要的思想，以便文档能够呼吸
- 不要有太多的重复，避免新闻稿风格－－这种风格就是通过不断重复思想以确保读者能够理解
- 不要使用多种时态，大部分时候用现在时就足够了．
- 如果还不是一个真正的好作家，就不要在文档中开玩笑．
-
限制信息的范围：每次只介绍一个概念
-
使用真实的代码示例：应该抛弃Foos,bars这些陈腐的用词．
- 代码示例应该在实际的程序中直接可用
-
保持简单，只要够用即可：写的不是一本书！
- 可以运行的软件胜过面面俱到的文档－－敏捷宣言
-
使用模板：帮助读者养成习惯