软件文档是以记录形式保存的信息，用于说明软件系统的预期功能、组织结构，以及使用、运行和维护方法。它既包括面向用户的操作说明，也包括在软件工程过程中产生的规格说明、设计描述、规程和记录。因此，文档的范围比用户手册更广：它既帮助人们实际使用软件，也支持整个软件开发生命周期中的沟通。文档的内容和形式取决于系统本身、目标读者及其开发过程。(ntrs.nasa.gov)
范围与读者
文档面向的读者在职责和已有知识方面各不相同。最终用户需要了解如何完成任务；开发者需要了解接口和实现；运维人员则需要系统运行方面的操作规程。读者分析决定了哪些概念需要解释、哪些术语适合使用，以及可以合理预期读者具备哪些知识。例如，熟悉某种编程语言并不一定意味着熟悉某个具体项目。(developers.google.com)
内部文档记录开发和维护系统所需的信息。外部文档则说明向用户提供的功能和接口。这两类文档可能有所重叠，尤其是在用户同时也是开发者的情况下。项目的 README 通常是读者了解项目的入口，介绍项目用途、初始设置、获取帮助的途径及维护者。在代码仓库托管平台上，它还可以引导读者查阅更详尽的文档和贡献指南。(ntrs.nasa.gov)
主要文档类型
文档可以按照其描述的软件制品或活动分类：
- 需求文档规定预期行为、约束条件和利益相关方的需求。软件需求规格说明书为审查这些需求是否得到准确记录提供依据。
- 设计文档描述软件架构、组件、接口及其相互关系，说明拟议系统如何满足需求。
- 开发与验证记录包括与实现和评估有关的计划、规程、报告及其他证据。
- 运行与用户文档介绍安装、配置、使用方法，以及与软件运行有关的规程。
这些内容不一定要分别存放在不同文件中。文档可以根据项目需要合并或拆分，只要所需信息仍然易于识别和使用即可。例如，NASA 的软件指导文件将文档内容与交付文档所采用的具体格式区分开来。(swehb.nasa.gov)
另一种分类方式着眼于读者的目的。Diátaxis 框架区分了四种形式：
- 教程提供有引导的学习体验，让读者通过实践掌握技能。
- 操作指南说明如何实现某个具体目标，并假定读者已具备相关能力。
- 参考文档提供客观的技术描述，供读者查阅。
- 解释性文档通过背景介绍、上下文说明和原因探讨，帮助读者加深理解。
这些形式相互补充。教程可以通过示例介绍某个接口，参考文档则对其进行系统描述，解释性文档则讨论其背后的设计。Diátaxis 区分了学习与实际操作，也区分了实践行动与概念理解；它是一种框架，而不是强制性的文档标准。(diataxis.fr)
编写与组织
面向软件的技术写作首先要明确目标读者、文档范围，以及读者希望达成的目标。文档可以明确说明其涵盖和不涵盖的内容。随后，文档结构应体现这些边界，而不是试图囊括所有相关细节。(developers.google.com)
导航与组织方式也是信息本身的一部分。参考资料可以按照应用程序编程接口（API）的结构组织，将方法归入所属的类，再将类归入所属的模块。面向任务的资料则按照实现目标所需的操作顺序编排。交叉引用将这些不同的组织方式联系起来，使各个页面不必重复介绍性内容。(diataxis.fr)
用词和示例必须与读者已有的知识相匹配。如果不能假定读者已经了解某些缩写、项目专用术语或不熟悉的实现细节，就需要加以解释。对于国际读者，采用简明措辞并避免使用带有特定文化背景的习语，也有助于翻译。(developers.google.com)
工具与发布
文档即代码方法将软件开发工具和工作流程应用于文档。作者使用版本控制、问题跟踪工具、纯文本标记、代码审查和自动化测试。Markdown 和 reStructuredText 等格式使文档变更能够与代码变更一同接受审查。这种方法还可以将文档列为接纳新功能的条件。(writethedocs.org)
文档生成器可以整合嵌入源代码中的信息。例如，Sphinx 提供了 autodoc 扩展，可导入 Python 模块，并将模块中的文档字符串纳入生成的文档。这样，参考资料便与在实现代码附近维护的说明关联起来。但这也会影响生成过程的执行：在生成文档时导入模块，可能触发该模块在导入时产生的副作用。(sphinx-doc.org)
发布工具和格式并不决定文档的教学目的。自动生成的参考资料、人工编写的教程和概念性解释可以共存于同一个文档系统中。(diataxis.fr)
准确性、测试与无障碍访问
文档质量的一个方面，是文档与其所描述的软件是否一致。可执行示例是检查这种一致性的一种方式。Sphinx 的 doctest 扩展会运行经过标记的代码片段，并核对其预期结果，帮助发现不再符合程序行为的示例。这类测试检查的是具体示例，而不能证明整份文档都正确无误。(sphinx-doc.org)
无障碍访问关注读者能否通过不同设备和辅助技术感知文档内容并进行导航。相关做法包括使用有意义的标题、描述性链接、图像替代文本、键盘操作支持和语义化标记。仅依赖颜色、屏幕位置或无标签图标的操作说明，在通过屏幕阅读器朗读或以不同方式显示时，可能无法传达原意。文档还可以明确介绍软件本身的无障碍功能。(developers.google.com)