17、项目文档编写指南

项目文档编写指南

在软件开发项目中，文档的编写至关重要，它能帮助开发者更好地理解系统，也能为后续的维护和扩展提供有力支持。本文将介绍如何构建项目文档，包括文档组合的构建、文档布局的搭建以及相关工具的使用。

构建文档组合

软件项目的文档种类繁多，从直接关联代码的底层文档，到提供应用程序高层概述的设计文件都有。常见的软件项目文档可分为以下三类：
1. 设计类 ：提供架构信息和底层设计信息的文档，如类图、数据库图等。
- 目的：描述软件的工作原理和代码组织方式，帮助开发者理解系统，也是新手了解应用程序的良好切入点。
- 类型：架构概述、数据库模型、带依赖和层次关系的类图、用户界面线框图、基础设施描述等。
- 特点：大多由一些图表和少量文本组成，图表的使用规范因团队和项目而异，但保持一致性即可。
- 示例工具：UML 提供了十三种图表，可覆盖软件设计的大部分方面，其中类图最为常用。不过，团队通常会根据自身经验创造自己的方法，例如使用 Dia、Microsoft Visio 或 OmniGraffle 等工具绘制架构图。
- 通用模板：设计文档的通用模板应包含标题、作者、标签（关键词）、描述（摘要）、目标受众、内容（含图表）和参考文献等内容。内容应控制在三到四个屏幕（以 1024x768 平均屏幕计）内，如需扩展，可拆分为多个文档或进行总结。

$ paster create -t pbp_design_doc design
Selected and implied templates:
  pbp.skels#pbp_desi