如何避免服务器文档与实际设置不同步？

我们拥有适用于我们环境的相当不错的文档（采用AsciiDoc格式），该文档最近允许另一个人在30分钟内从头开始重新创建整个设置。
但是，我注意到在初始设置后，很容易发生对系统进行小的更改（例如：inetd被禁用，我的IMAP服务器在另一个端口上监听ManageSieve连接，新的路由器被添加到exim配置中）不会立即出现在文档中（如果有的话）。

我的想法是通过（部分地）从配置文件和其中的注释中生成文档来避免此问题-一种实现此方法的方法可能是将/etc其/usr/local/etc放入某些源代码管理系统（例如git），然后运行该脚本可在每次提交时重新生成文档。但是，我不确定这是否会过大和/或太难解决（毕竟，我不想要文档中源文件的完整副本，而只是差异）。

其他人如何避免服务器文档过时-是否有一种很好的方法可以使它们自动保持同步，或者您只是有纪律在修改系统的同时更新文档？

您永远不会摆脱一些文档，但是正如您所知，有些系统可以集成到您的变更过程中，以涵盖很多内容。

• 使用配置管理工具（例如puppet或cook）。
• 以更改控制的方式存储您的配置。（如git或SVN）
• 确保配置是人类可读/可访问的（即纯文本，可搜索的数据库）

这样，通过将部署信息存储在配置项或代码中作为您进行更改的系统的一部分，可以强制执行我们通常都错过（或不打扰）的下层文档。这也带来了额外的好处，该过程在将来变得更加可重复。

外部文档确实仍然需要更新，但是它变得非常高级，指向“ deploy x”或“ deploy y”的指针，而不是冗长的命令/文件列表。另外，这使得文档更改的频率降低且更加轻松，这也意味着完成文档的可能性更大。

同样在您回家冲泡啤酒之前，有人可能已经写了一些东西来管理您想要的东西。

如果仅管理一个或两个小型系统，则设置大型配置管理系统（例如puppet或Chef）似乎有些过头。（但是，如果您计划将来拥有更多系统，请立即执行！）

对于这样一个小设置，我建议使用类似etckeeper，程序这使/etc成一个git存储库，并提供了一些有用的功能，喜欢做，只要你安装，升级或删除软件包自动提交。

每次在系统上进行更改时，只需更新文档即可。AKA Change Management。

大多数公司以荒谬的方式实施变更管理，以至于使变更管理变得糟透了，这一事实不应损害基本概念的效用或阻止您正确执行。

我曾经使用htmlWiki来跟踪我的所有配置。现在，我在一家Windows商店（（颤抖的）SharePoint中工作），所以现在我使用创建的Word文档“模板”来跟踪我拥有的每个系统以及所做的每个配置更改，这听起来并不像听起来那么糟糕。系统只是其他程序的千篇一律的副本，可以全部合并到同一文档中。（并且我将所有我的文档的本地副本保存在硬盘中，实际上以合理的方式进行组织，除了将它们扔到任何人的SharePoint网站的无组织的堆上。）

最大的挑战实际上是花时间编写文档，这是通过将文档时间添加为进行更改的时间来实现的。因此，并不是那么难，尤其是如果您有点笨拙，并且不介意告诉人们退出并排队等候，因为您现在正忙于解决他们的问题。