Python高级编程（第2版）

第9章　文档化你的项目

文档是经常被开发人员忽略的工作，有时也会被管理者忽略。这往往是由于在项目生命周期结束的后期缺乏时间，以及人们认为他们不擅长写作。其中一些人确实写不好，但他们中的大多数能够完成一个良好的文档。

在任何情况下，匆忙编写文档的结果是文档会变得一团糟。大多时候，开发人员讨厌做这种工作。当现有文档需要更新时，情况会更糟。因为经理不知道如何处理更新，许多项目只是提供简陋而又过时的文档。

但是在项目开始时设置一个文档过程，并且将文档看作是代码模块，这会使得文档的编写更加顺利。当遵循几条规则时，写作甚至会很有趣。

本章提供了一些开始文档化项目的提示。

• 7项技术写作规则，这是最佳实践的概述。
• reStructuredText入门，它是在大多数Python项目中使用的纯文本标记语法。
• 建立良好的项目文档的编写指南。

9.1　7项技术写作规则

编写良好的文档在许多方面比编写代码更容易。大多数开发人员认为这很难，但通过遵循一组简单的规则，它会变得非常容易。

我们不是在这里谈论写一本诗集，而是一个全面的文本，可以用来理解一个设计、一个API或任何构成的代码库。

每个开发人员都能够输出这样的材料，本节提供了7个规则，可以应用在所有情况下。

• 两步写作：专注于想法，然后审查和塑造你的文本。
• 定位读者：谁会读？
• 使用简单的风格：保持直接和简单。使用好的语法。
• 限制信息范围：一次引入一个概念。
• 使用现实中的代码示例：应避免使用“Foos”和“bars”。
• 使用轻量且充分的方法：你不是在写一本书！
• 使用模板：帮助读者习惯。　

这些规则主要来自AndreasRüping编写的书Agile Documentation:A Pattern Guide to Producing Lightweight ...