文档撰写是程序员的另一个最大痛点，许多程序员宁愿写更多的代码也不愿写一行文档。
这可能是跟人脑的工作方式有关，写程序是利用左脑，注重逻辑思维，而写文档则是利用右脑，注重发散思维。这截然不同的思维方式是很多程序员不擅长写文档的一个原因。
软件文档是过程管理的产物，是软件质量的另一种体现，是软件开发中不可缺少的部分。我们需要文档来记录软件相关信息、沟通开发人员与客户的需求、软件设计等内容。
如果在互联网上搜索，或者直接询问ChatGPT通过一句话描述生成软件的需求规格说明，概要设计文档和详细设计文档，大多会得到模板化的回答，实际的用处不大。我们关注的重点是用户和程序员的真正关心的内容，对需求的描述进行分析，产生实际意义的设计模型。
通过AI大模型，我们确实可以利用文档的自动生成来减少文档工作。然而软件的文档并不是独立的，而是一组相关文档的集合。这就需要大量的AI提示词，并且这些提示词之间具有一定的逻辑关系。因此我们可以建立一个软件的设计元模型，充当AI提示词的作用，生成一致的文档体系。
下面是对软件的常用文档类型进行提示设计：
1.需求规格说明
主要记录软件的功能需求、非功能要求（例如性能、安装需求等）和其他规范性需求。通常由产品经理撰写，以确保软件开发符合客户的期望。其中功能需求是需求规格说明的难点，也是核心内容，其他的需求通常都有很多套话和模板。
这里的提示词是：
对用户的需求描述进行分析分解为若干业务流程，业务流程包括用户角色，流程步骤和具体操作。每个业务流程都有多个步骤，每个步骤都有一个角色，每个角色对界面进行一系列的操作，查看或者处理领域中的数据模型。
2.概要设计文档
这个文档记录了软件的运行流程、架构、系统设计和相关算法。通常由产品设计相关人员来撰写。概要设计中架构信息一般也有固定和现场的模板，复杂和难点在于功能菜单的设计。菜单是一个层次的树状模型，一般情况下叶子菜单会对应具体的界面操作。对于界面原型，ChatGPT目前还无法画出，因此这里只做描述。
这里的提示词是：
根据用户需求列出整个菜单结构，详细描述每个菜单对应的界面，并列出界面中的界面要素如按钮，表格，图表等展示和交互的组件。
3.详细设计文档
主要记录了软件系统的实现细节，包括类图设计、数据库设计、接口设计等信息。通常由开发人员本身编写。其中类图，ER图等目前ChatGPT也无法直接画出，因此也是详细描述。
这里的提示词是：详细描述用户需求中的数据模型和服务接口，其中数据模型是对应于数据库的设计，列出需求中所有的数据表结构以及包含的字段信息。服务接口是对数据模型进行操作的HTTP协议的网络接口，接口类型一般为POST，通过网络接口可以对数据进行增删改查，请列举出相应的服务接口。
4.软件测试文档
通常记录软件测试的用例、测试计划、测试报告等内容。包括单元测试，集成测试等。用于确保软件的正确性、完整性、可靠性和性能。在单元测试中一般是针对功能菜单中的界面要素进行测试，而集成测试则针对业务流程进行测试，测试报告需要根据测试结果进行统计，因此只利用ChatGPT来编写测试用例。
这里的提示词是：根据上述功能菜单中的界面信息编写单元测试用例，针对界面中的要素设计用例中的操作。根据上述需求规格中的业务流程中的步骤操作编写流程测试的用例。每个步骤作为一个用例，步骤中的操作过程则是用例的具体操作细节。
5.软件用户手册
为最终用户提供了软件的详细使用说明，通常是基于带有图形用户界面的应用程序进行编写。一般情况下用户手册的内容分为两个部分，一个是功能说明，一个是操作流程。
这里的提示词是：根据上述功能菜单，分别描述每个功能模块。然后再根据需求规格中的流程模型，描述每个流程，并在流程步骤的操作中涉及界面的地方插入菜单界面的描述和设计数据模型的地方插入数据结构的描述。
往期文章链接：
从五个维度比较：代码、无代码、低代码、AI提示代码、AI低代码
原创 | 作者 | 薛丹，国防科技大学博士，资深程序员。版权所有，转载须联系授权并注明来源