软件环境文档清单[关闭]

Question

我在一家保险公司工作。我们有自己的开发部门，由近 150 名员工和一些提供商组成（大部分是外包和定制应用程序）。在我们公司，我的团队制作了我们所说的非功能逻辑库。也就是说，软件库用于处理与我们部门所有开发团队相关的事务，例如安全、Web 服务、日志记录、消息传递等。大多数或这些工具要么是从头开始制作的，要么是根据事实上的标准改编的。例如，我们的记录器是一个基于 Log4J 的附加程序，它还将日志消息保存到数据库中。我们还定义在应用程序中使用哪些库，例如要使用哪个 Web 服务框架。我们在所有组织中几乎都使用 JavaEE 和 Oracle AS（以及一些 Websphere 应用程序服务器）。

这些项目中的大部分都记录了其架构（用例、UML 图等），并且通常生成的文档都是可用的。现在我们看到的是，对于用户来说，有时很难使用我们提供的库，并且他们不断地提出问题，或者他们根本不使用它们。

所以我们计划为他们生成一个更友好的文档，所以我的问题是：软件文档应具备哪些最佳实践或清单？

我想到了一些事情：

1. API参考指南
2. 快速入门教程
3. API 生成的文档。
4. 必须可搜索
5. 网络访问

它还应该有什么？另外，根据您的经验，维护（保持最新）和发布此类文档的最佳方法是什么？

Answer 1

也将您的文档置于版本控制中。

确保每个页面都有版本号，以便您知道用户从哪里阅读。

启动 CI 服务器并在更新时将文档推送到实时文档站点。

像代码审查一样进行文档审查。

狗粮吧:)

善良，

担