『Python高级编程』学习笔记之二: 第十章——编写项目文档

7条适用任何情况的规则:

1、分两步编写: 先聚焦于思想, 然后审查和修正文档

第一步先把思想写下来, 第二步时才重新阅读整个文本, 并对其进行润色 

2、以读者为目标: 谁将读这个文档?

明确你的读者有哪些, 并应用一个简单的规则: 每个文档应该只有一类读者。在文档中提供一些简单那的介绍性文字, 说明文档的相关内容, 指导读者找到合适的部分

3、使用简单的风格: 保持简单明了, 使用良好的语法

①使用简单的句子, 句子不应该长于两行

②每个段落应该由3~4个句子组成, 最多表达一个主要的思想

③不要有太多的重复, 避免新闻稿风格

4、限制信息的范围: 每次只介绍一个概念

段落应该被放在具有意义的标题之下, 整个文档的标题应该在一个短句中概述其内容

5、使用真实的代码示例: 应该抛弃Foos、 bars这些陈腐的用词

一个常用的方法是确定每个代码示例可以被剪切并粘贴到实际的程序中

6、保持简单, 只要够用即可

7、使用模板: 帮助读者养成习惯

①reStructuredText

②markdown    : GitHub常用的

 

你可能感兴趣的:(编程,python,总结,文档)