软件文档
软件文档是伴随计算机软件或嵌入在源代码中的文本或插图。该文档要幺说明软件的运行方式或如何使用该文档，并且可能对扮演不同角色的人意味着不同的事物。
文档是软件工程的重要组成部分。文档类型包括：
- 要求- 确定系统属性，功能，特征或质量的语句。这是实施或已实施的基础。
- 体系结构/设计 - 软件概述。包括与用于设计软件组件设计的环境和构建原理的关系。
- 技术 - 代码，算法，接口和API的文档。
- 最终用户- 最终用户，系统管理员和支持人员的手册。
- 营销 - 如何销售产品和市场需求的分析。
类型
要求文档
需求文档是特定软件要做或将要做什么的描述。它在整个开发过程中都用于传达软件的功能或打算如何运行。它也被用作协议或有关软件将要做什么的协议的基础。参与软件生产的每个人都会生产和消耗要求，包括：最终用户，客户，项目经理，销售，市场营销，软件架构师，可用性工程师，交互设计师，开发人员和测试人员。
要求有多种样式，符号和形式。需求可以像目标一样（例如，分布式工作环境），靠近设计（例如，可以通过右键单击配置文件并选择“构建”函数来启动构建），以及介于两者之间的任何内容。可以将它们指定为自然语言的陈述，如绘制的数字，详细的数学公式，或者是所有人的组合。
需求文档的差异和复杂性使其成为一个可靠的挑战。要求可能是隐含的，很难发现。很难确切地知道需要多少文档，以及架构和设计文档的数量，并且考虑到要阅读和使用文档的各种各样的人，很难知道如何进行文档要求。因此，需求文档通常不完整（或不存在）。没有适当的要求文档，软件更改将变得更加困难，因此更容易出现错误（软件质量降低）和耗时（昂贵）。
需求文档的需求通常与产品的复杂性，产品的影响以及软件的预期寿命有关。如果软件非常复杂或由许多人开发（例如，手机软件），要求可以帮助更好地传达要实现的目标。如果该软件至关重要，并且可能对人类的生活产生负面影响（例如核电系统，医疗设备，机械设备），则通常需要更正式的要求文档。如果预计该软件只能播放一个或两个月（例如，专门为某个广告系列开发的非常小的手机应用程序）可能几乎不需要文档。如果该软件是后来构建的第一个版本，那么在管理软件的更改并验证软件修改时，需求文档非常有用。
传统上，需求文档（例如使用文字处理应用程序和电子表格应用程序）中指定了要求。为了管理需求文档（以及一般软件文档）的增加复杂性和变化的性质，提倡以数据库为中心的系统和特殊用途需求管理工具。
在敏捷软件开发中，需求通常是用户故事，并带有随附的接受标准。
建筑设计文档
体系结构文档（也称为软件体系结构描述）是一种特殊的设计文档类型。在某种程度上，架构文档是代码的第三个衍生文档（设计文档是第二个衍生文档，而代码文档是第一个）。架构文档中的几乎没有代码本身。这些文档并没有描述如何编程特定例程，甚至没有描述为什么以其形式存在该特定例程，而只是提出了激励这种例程存在的一般要求。一个好的架构文档缺乏细节，但解释很厚。它可能建议使用较低级别设计的方法，但将实际的勘探贸易研究留给其他文件。
设计文档的另一种类型是比较文件或贸易研究。这通常会采用白皮书的形式。它着重于系统的一个特定方面，并提出了替代方法。它可以在用户界面，代码，设计甚至建筑级别上。它将概述情况是什么，描述一个或多个替代方案，并列举每个情况的利弊。一份良好的贸易研究文件对研究很庞大，清楚地表达了其想法（不依赖钝术语来使读者眼花azz乱），最重要的是公正。它应该诚实，清楚地解释其最佳解决方案的成本。贸易研究的目的是设计最佳解决方案，而不是推动特定的观点。没有结论是完全可以接受的，或者得出结论，没有一个替代方案比基线要好，因此可以进行更改。它应该作为一项科学努力，而不是作为营销技术。
企业软件开发中设计文档的一个非常重要的部分是数据库设计文档（DDD）。它包含概念，逻辑和物理设计元素。 DDD包含与数据库需求互动的人们的正式信息。准备它的目的是创建一个共同的来源，以被现场中的所有玩家使用。潜在用户是：
在谈论关系数据库系统时，该文档应包括以下部分：
- 实体 - 关系模式（是否增强），包括以下信息及其明确的定义：
- 实体集及其属性
- 关系及其属性
- 每个实体集的候选密钥
- 属性和元组约束
- 关系模式，包括以下信息：
- 表，属性及其属性
- 视图
- 诸如主要密钥，外键，诸如限制因素
- 参考约束的基数
- 引用约束的级联政策
- 主键
包括现场所有演员都使用的所有信息非常重要。更新文档也非常重要，因为数据库中的任何更改也发生。
技术文档
对于与源代码相关联的代码文档（可能包括读取文件和API文档）非常重要，但详细说明并非如此，以至于它变得过于耗时或难以维护它们。通常发现各种方法和概述文档指南特定于API作者记录的软件应用程序或软件产品。开发人员，测试人员以及最终用户可以使用此文档。如今，在电力，能源，运输，网络，航空航天，安全，安全，行业自动化以及其他各种领域的领域中都可以看到许多高端应用。技术文档在此类组织中变得很重要，因为随着体系结构的变化，基本和高级信息可能会在一段时间内发生变化。有证据表明，良好的代码文档的存在实际上会降低软件的维护成本。
代码文档通常被组织成参考指南样式，从而使程序员可以快速查找任意功能或类。
嵌入在源代码中的技术文档
通常，诸如Doxygen ， NDOC ， Visual Expert ， Javadoc ， JSDOC ， Eiffelstudio ， Sandcastle ， Robodoc ， Pod ， Twintext或Universal Report等工具可以用于自动生成代码文档，也就是说，他们提取评论和软件合同在可用的地方，从源代码，并以文本或HTML文件等形式创建参考手册。
出于各种原因，自动生成文档的想法对程序员具有吸引力。例如，由于它是从源代码本身中提取的（例如，通过注释），因此程序员可以在参考代码时编写它，并使用用于创建源代码来制作文档的相同工具。这使保持文档的最新状态变得更加容易。
一个可能的缺点是，只有程序员才能编辑这种文档，并且取决于它们来刷新输出（例如，通过运行CRON作业来每晚更新文档）。有些人将其描述为专业人士，而不是骗局。
识字编程
受人尊敬的计算机科学家唐纳德·诺斯（Donald Knuth）指出，文档可能是一个非常困难的事后思考过程，并提倡识字编程，并与源代码同时和位置编写，并通过自动手段提取。编程语言Haskell和Coffeescript对简单的识字编程形式具有内置的支持，但是这种支持并未得到广泛使用。
明确的编程
阐明编程是识字编程在实际编程环境中实际应用的结果。明确的范式提出了单独存储源代码和文档。
通常，软件开发人员需要能够创建和访问不会成为源文件本身的一部分的信息。这样的注释通常是几项软件开发活动的一部分，例如代码步行和移植，其中第三方源代码以功能方式分析。因此，注释可以帮助开发人员在软件开发的任何阶段，在软件开发的任何阶段，正式文档系统都会阻碍进步。
用户文档
与代码文档不同，用户文档只需描述如何使用程序即可。
在软件库的情况下，代码文档和用户文档在某些情况下可能有效地等效且值得一致，但是对于一般应用程序，这并不常见。
通常，用户文档描述了程序的每个功能，并协助用户实现这些功能。对于用户文档而言，不要混淆，并使他们保持最新非常重要。用户文档无需以任何特定的方式组织，但是对于他们来说，拥有详尽的索引非常重要。一致性和简单性也非常有价值。用户文档被认为构成了指定软件将要做什么的合同。 API作家在编写良好的用户文档方面非常有成就，因为他们很了解所使用的软件体系结构和编程技术。另请参阅技术写作。
用户文档可以以各种在线和打印格式生产。但是，可以通过三种广泛的方式组织用户文档。
- 教程：教程方法被认为是新用户最有用的，其中他们通过完成特定任务的每个步骤进行指导。
- 主题：一种主题方法，其中章节或部分集中在一个特定感兴趣的领域上，对中级用户更为普遍。一些作者更喜欢通过基于知识的文章来传达他们的想法，以促进用户需求。这种方法通常由动态行业（例如信息技术）实践。
- 列表或参考：组织原理的最终类型是一种通常通过交叉引用索引在字母顺序或逻辑上简单地列出的命令或任务。后一种方法对那些确切知道他们要寻找的信息的高级用户更有用。
用户对软件文档的普遍投诉是，这三种方法中只有一种被采用了其他两种方法。通常将提供个人计算机的软件文档限制为在线帮助，该帮助仅提供有关命令或菜单项的参考信息。辅导新用户或帮助更多经验丰富的用户充分利用程序的工作留给了私人出版商，这些发行商通常会受到软件开发人员的重大帮助。
撰写用户文档
像其他形式的技术文档一样，良好的用户文档受益于有组织的开发过程。在用户文档的情况下，该过程通常在行业中发生，包括五个步骤：
- 用户分析，过程的基础研究阶段。
- 计划或实际文档阶段。
- 审查草案，这是一个不言自明的阶段，在上一步中构成的草案寻求反馈。
- 可用性测试，从经验上对文档的可用性进行了测试。
- 编辑，第三和第四步中收集的信息的最后一步用于制作最终草案。
营销文档
对于许多应用，有必要有一些促销材料来鼓励休闲观察者花更多的时间学习该产品。这种文档形式具有三个目的：
- 激发潜在用户对产品的兴趣，并灌输他们更多地参与其中的产品。
- 告知他们产品到底有什么作用，以便他们的期望与他们将收到的收益一致。
- 解释该产品在其他替代方案方面的位置。
文档和敏捷发展争议
“开发人员对文档的抵抗是众所周知的，不需要重点。”这种情况在敏捷软件开发中尤为普遍，因为这些方法试图避免任何不必直接带来价值的不必要的活动。具体而言，敏捷宣言提倡“对“工作软件”评估“超过综合文档”，这可以愤世嫉俗地解释为“我们想花费所有时间编码。请记住，真正的程序员不编写文档。”
但是，软件工程专家之间的一项调查显示，该文档绝不是敏捷开发中不必要的。然而，人们承认，发展中存在动机问题，并且可能需要针对敏捷开发（例如通过声誉系统和游戏化）量身定制的文档方法。