软件环境文档清单

Question

我为一家保险公司工作。我们有自己的开发部门，由近150人组成，还有一些供应商（外包和定制应用程序）。在我们公司，我的团队制作了我们称之为非功能逻辑库的东西。也就是说，软件库处理与我们部门中所有开发团队水平相关的事情，例如安全性，Web服务，日志记录，消息传递等。大多数或这些工具都是从零开始制定的，或者是事实上的标准的改编。例如，我们的记录器是基于Log4J的appender，它也将日志消息保存到数据库中。我们还定义了在应用程序中使用哪些库，例如使用哪些Web服务框架。我们在所有组织（包括一些Websphere应用程序服务器）中都使用了JavaEE和Oracle AS。

这些项目中的大部分都有其架构记录（用例，UML图等），通常生成的文档可用。 现在我们已经看到，对于用户来说，有时很难使用我们提供的库，并且不断提问或者他们根本不使用它们。我们的问题是： 什么是最佳实践或软件文档应该有的清单？

东西在我脑海中：

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

还有什么应该能有多少？此外，根据您的经验，维护（保持最新版本）的最佳方式是什么，并发布此类文档？

Answer 1

保留您的文档在版本控制中。

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

获取CI服务器并在更新时将文档推送到LIVE文档网站。

做文档评论就像你会代码评论。

狗的食物吧:)

善良，

丹