我的任务是设置和管理一个全新的实验室环境，该环境由许多扮演不同角色的机器组成。其中包括一台 VM 主机、几台 Web 服务器、几台数据库服务器等。
作为此实验室环境的一部分，需要记录非常具体的需求和流程，例如，我们不想打开自动 Windows 更新，并且我们希望捕捉很多想法以便向多个不同的方（高管、经理、开发人员、IT 经理、QA 人员）解释。
因此，当我进行设置时，我真的希望将这些对话记录在某种正式文档中。我打算继续创建一个 Word .doc，将每个服务器角色组织成几个独立的部分：
- 执行摘要
- 维护需求
- 已安装软件清单
- 可用硬件
- 硬件默认设置
我想知道的是，在为这些机器创建文档时，是否有更好的模板可以遵循。我希望我最终创建的内容足够好，以便其他人在需要时重建机器。
答案1
良好的文档系统最重要的是：
- 易于更新（或者人们不会更新它，这使得它变得比无用更糟糕）
- 易于访问——从任何位置、通过多种设备。
- 组织良好——人们可以轻松找到所需的信息，并且相同信息的重复最少。
我试过 Word 文档。它们在这 3 点上都失败了。Word 文档很难更新，最终会导致人们拥有不同的副本，等等。
我发现最适合我使用的系统是 wiki。DokuWiki 对我来说非常实用。我可以从任何地方轻松访问和更新它。
我的 wiki 中列出了描述整个网络设置的页面，这些页面链接到每个服务器、集群和应用程序的页面。这样，有关特定项目的所有详细信息都保存在单独的页面上，并且可以从每个相关位置链接到该页面 - 当某些内容发生变化时，我只需在一个页面上进行更改，就可以轻松找到所需信息。
它还允许您指定命名空间模板，因此当我创建一个新的服务器页面时，它会预先填充表格以输入 IP 地址、硬件配置等。所有空白字段都写有 FIXME，因此我可以在整个 wiki 中搜索 FIXME 并查看文档中缺少什么。
如果您真的想更进一步，您可以编写插件来获取配置文件等内容，解析它们，并以易于阅读的格式显示它们。例如，我编写了一个名为 PatchPanel 的插件，它获取网络配线架的文本描述并绘制一张带有每个端口位置标签的图片。
http://blog.emsley.ca/2014/04/documentation.html对如何设置它有一个更完整的描述（免责声明：链接到我的博客，但完全符合主题）。