技术文档与软件设计文档

Question

我正在尝试开始一个关于已经完成/开发的类库的文档。

文档的目的是让其他开发人员使用，以便了解类库中包含了哪种方法以及如何使用它们。更具体地说，像Javadoc工具这样的文档为类的每个方法和属性提供了基于XML注释的文档。

到目前为止，我一直在阅读关于文档类型的文章，似乎技术规范和软件设计文档就是那些提供此类信息的文档。

但我对它们感到困惑，因为我无法从我已经读过的一些文章中看到很多不同之处。

例如，这里说，软件设计文档被用来给软件开发团队提供软件项目体系结构的总体指导。这里表示，技术文档用于加入软件项目的新开发人员。什么样的信息可以被介绍给这个项目？

从这个角度来看，这些文档似乎试图让软件开发人员熟悉到目前为止开发的内容。但是，有什么区别，哪一个是为了我的目的呢？

Answer 1

什么是技术文档?

真正的定义:技术文档是指任何普通凡人由于某些必要的专业知识而无法理解的文档。

坏消息是，它不会帮助你决定把什么放在里面。好消息是，从现在开始，你可以自己使用这个概念来限定任何你不理解的东西：“嗯！这些会计准则似乎是一份非常技术性的文件”(除了会计师之外，所有的人都会点头，默默地同意你的观点)。

你的文档的目标是什么？

真正的问题是:对于技术写作，和任何写作一样，第一个问题是知道目标受众是什么，以及本文档的主要目的是：

• 这是给新队员的吗？最重要的是概述(例如体系结构和层、主要组件)、高级域模型(即上下文地图)以及一些信息(例如目录结构、使用的工具集、命名约定、链接到其他重要文档以供阅读)。这些细节无论如何都会出现在代码中，无论是在不言自明的、干净的代码中还是在有用的注释中。
• 这是给图书馆用户的吗？您的javadoc或doxygen将根据嵌入在代码中的注释(希望易于维护)生成合适的参考文档。不幸的是，这些详细的信息不能让您轻松地理解库的设计。同样，您需要提供一些关于库的体系结构的高级概述，以及它的不同组件是如何交互和相互依赖的。如果您的库是一个独立销售的商业产品，那么这种文档是必须拥有的。

一个致命的假设是，您可以做一个“技术文档”来满足任何技术需求。团队(必须了解内部结构)和用户(需要理解用例和界面)所要理解的细节级别通常是非常不同的。

关于

的一些建议

Grady Booch在他的书“面向对象的分析和设计技术”中公开了所需软件文档的内容：

• 高层系统结构
• 体系结构中的关键抽象和机制
• 演示系统关键方面的内置行为的方案。

他还提出了一个非常具体的观点：

更好的方法是记录这些高级结构，这些结构可以用符号的图表表示，但在编程语言中没有直接的语言表达式，然后向开发人员推荐某些重要类的接口以获得战术细节。

Answer 2

文档有两种基本类型:用户指南和参考文档。

和

都可以包含关于总体设计的部分，以避免重复，但是将从不同的角度来描述它。

(一些公司也承认概览是一个单独的类别，见下文。)

参考文档详细而准确地列出了产品公共接口的全部内容:每个开关和参数意味着什么，哪些输入被认为是有效的，哪些是在每种情况下返回的等等。

• 注意公共接口这个词:它的主要目标是指定观察到的行为的哪些细节是官方保证的，因此可以依赖。(省略说明或暗示所有其他内容均为实现细节，如有更改或中断，恕不另行通知。)
• 还请注意“整体”一词。参考文献的主要卖点是它的完整性。如果它不在引用中，它就不存在(正式的)。如果我读过关于某个主题的参考资料，我可以肯定，我现在知道关于这个话题的一切，也不会有令人讨厌的惊喜。
  • 因此，尽管参考资料可以用作学习材料，但它的主要用例是填补空白。

由于设计原则直接体现在公共接口的结构和组织中，参考文档可以在列出它们的详细信息之前包含关于产品接口和行为的部分和方面的概述部分(如果只是为了避免在单个API的条目中重复它们)。

• 同样，重点是公共界面，所以解释应该集中在用户可见的细节上，这些细节对于理解产品的组织和行为至关重要，对此不重要的技术细节可以省略或挥手。

用户指南的目的是演示产品的作者如何设想如何使用公共接口来解决实际问题和/或此类问题:预期的使用模式、典型的一般问题和建议的解决方案(特定API的本地问题似乎属于它们的参考条目)。

用户指南是有意不完整的，只给出了“大图”和关键指针，并将其留待参考来详细说明。

用户指南也可以有概述文本，但是这里概述的重点是使用模式:什么应该在什么之后被称为什么，从什么地方等等。

• 注意这个词。这是一项建议：“这是我们打算成为首选的方式”。可以(或不能)从直接引用文档域调用什么。

有些公司，如微软，将最高级别的概述分离成一种单独的文档。在MSDN中的许多地方，您会看到关于X的一节分为：“约X”、“使用X”和"X引用“。

正如你所看到的，用户指南和参考信息是相辅相成的，涵盖不同的主题，并从不同的角度解释事物。虽然指南在短期内对用户更有利，但从长远来看，参考文档对用户更有利。

• 由于引用是完整的，所以它比用户指南“优越”，因为用户指南中的任何信息都可以从它中推断出来--尽管代价是学习曲线更陡峭。
• OTOH用户指南要维护的工作量要小得多，尤其是在界面变化迅速的情况下。缺点是你的用户永远不确定他们想做什么，除了你给出的几个例子是否有效，允许在什么地方使用什么语法等等--导致大量浪费他们的时间。

man页面是一个典型的参考文档示例。一些man页面作者(例如rsync)试图添加用户指南部分--通过这样做，很难找到所需的参考资料。