通过技术文档降低软件维护和现代化的成本

一、概述

文件的准备是软件开发和发布过程中的一个重要阶段。不是所有的公司都对这个阶段给予足够的重视。这种漫不经心的开发方式对软件的维护和进一步的进化产生了负面影响。

文档可以让你估计开发的成本，并协调未来系统的功能。如果对某项功能的开发成本和时间有争议，文档可以成为客户的明确保证。如果需要改进应用程序，文档将促进开发过程，并清楚地了解是否有可能将新功能整合到现有系统中。

二、我们所说的软件文档是什么意思？

软件文档是一组详细描述软件的技术特征和消费者素质的文件，并提供有关其开发、应用和维护过程的信息。这些文件通常包括手册、用户说明和指南、软件审查、规格、测试程序等。

软件文档按其类型可分为4类。

• 设计（架构）文件。它描述了项目的主要规定、目标、任务和阶段，适用于软件的开发及其工作环境。它是对软件的总体概述，主要是为从事该项目的专家准备的。

• 技术文件。有时，绝对所有的软件文档都被称为技术文档，尽管这并不完全正确。技术文档包括对程序代码和功能、数据结构、算法、API和界面的描述。此外，它还详细说明了软件开发的过程，其工作原理和操作顺序。

这些材料通常与程序的源代码一起提供，或以注释的形式嵌入其中。为了简化技术文件的创建和更新，可以使用专门的模板，或者在文档生成器（Javadoc、Doxygen、NDoc等）的帮助下自动完成。

• 用户的文件。如果说前两类材料是针对专家的，那么这一类则是针对软件用户的。它不包含对代码和操作原理的复杂技术描述。用户文档的重点是描述软件的功能和操作的规则。最常见的用户文档格式包括《用户指南》和《用户参考》。它还经常包括故障排除说明和对常见问题的回答。

• 营销文件。营销材料有助于吸引目标受众对产品的注意，并告诉他们产品的功能、特点和好处。与用户文件相比，营销文件要短得多。它通常由一个宣传小册子组成，目的是让用户熟悉程序或应用程序。

三、谁负责准备软件文件？

技术专家为软件开发技术文件。这位专家几乎准备了所有类型的材料，包括用户指南和用户参考，专家的技术项目，营销文本等。

技术作家的工作职责。

• 根据内部（公司）、国家或国际标准设计技术文档。

• 保持更新，在软件更新时对文档进行修改和补充。

• 根据指定的参数准备图形和媒体材料（图、图表、截图、视频指南）并将其纳入技术文档。

• 测试和分析新的程序和应用程序，运用在编写文档时获得的经验和知识。

• 从所有项目参与者那里收集有关软件的必要信息：开发人员、经理、设计师、测试人员、客户。

• 将技术文档翻译成外语，准备技术报告，并参与软件实施过程。

四、技术文件和技术任务之间的区别

技术任务和技术文档是两个不同的文件。技术任务回答了 "应该做什么 "的问题，由业务分析员在项目开始时编写。技术文档是由技术作家开发的。这个文件是在技术任务之后创建的，它回答了 "应该怎么做 "的问题。

五、质量文件应该是什么样的？

1. 结构化

拥有一个清晰的结构是对软件文档最重要的要求之一。它必须有逻辑地组织成章节和子章节，并有段落、列表和其他文本格式的元素。如果我们谈论的是针对用户的材料，仅有文字描述是不够的。需要有高质量的程序截图。可以开发视频材料，但它们不能完全取代文字材料。

2. 整体性

所有的软件文件都应该采用统一的格式，包括面向员工的项目和技术文件以及面向用户的材料。它应该与公司发布的其他文件保持一致，并遵循统一的企业风格。一个好的解决方案是将准备文件的过程标准化，以避免将来出现差异。

3. 信息化

对高质量的软件文档的另一个重要要求是，它应该是清晰和有信息的。为了实现这一目标，有必要在数据量和其表现形式的简单性之间取得平衡。信息太少和太多都是不好的选择，特别是在涉及到用户文档的时候。一方面，没有必要使其过于肤浅和简单化，另一方面，你也不应该使材料过于复杂化。

4. 相关性

好的技术文件应该是为特定的目标受众设计的。在准备材料之前，有必要确定这些材料对哪些员工或客户是有用和合适的。也有必要了解受众的专业知识水平，以及文件可以解决哪些任务和问题。

六、拥有软件文档的好处

有了技术文件，就有可能。

1. 更精确和快速地估计开发成本，协调系统的功能。

如果需要升级应用程序，文件将促进现代化的进程，并允许你更准确地预测现有系统中新功能的成本。

2. 缩短开发时间。

有了技术文档，开发人员很快就能理解他们正在工作的内容，并且更容易接受遗留系统。而在没有项目文档的情况下，很大一部分预算将被用于研究 "如何工作"、"是什么 "和 "为什么是这样"。而这大约是分配给项目的预算的30%。

3. 促进代码维护和改进的过程。

你将清楚地了解是否有可能将新功能整合到现有系统中。

4. 减少团队工作中固有的风险

当员工离开公司时，他们会带走他们所做的部件的知识。开发和维护晦涩难懂的零件变得非常昂贵--有必要探索它现在的工作方式，并在当前的行为之上完成新的东西。

5. 为用户在系统的帮助下解决自己的应用任务提供可能。

用户文档描述了软件的所有功能以及如何使用它。这使人们能够快速和容易地浏览软件。

文档有助于将不同的数据系统化，同时也为有效的管理决策创造了基础。