如何编写和维护软件对外服务文档

安装某个软件不算什么难事，但记住如何安装、初始化和交付它却是一件难事，除非你经常重复这件事，所以还是要记录下来，等需要时再做参考。

如果我们安装的软件需要对外提供服务，这时我们更应该做好文档记录。

文档不仅是给自己看的，还要让调用方、运维同事、接手的人能安全、正确、持续地使用它。

文档要覆盖：服务是什么、怎么用、怎么接入、怎么跑、怎么出事时救火、怎么长期维护。

文档的主要目的是让“使用方”能正确接入并使用，让“运维/接手者”能在不出事故的前提下部署、升级、排障、下线。

在编写文档时应该有以下组成部分或着自检项目：

1. 文档给谁看的？谁写的？什么时间写的？
2. 这个服务是啥，干啥的，有什么用，用在哪里？
3. 服务的负责人是谁，使用人是谁？
4. 如何安装的？在哪里安装的？有什么依赖？
5. 如何初始化的？如何配置的？配置某个参数是否需要重启服务？
6. 如何判断服务是否正常？
7. 是否配置了自启动？如何启动、关闭和重新启动？
8. 如何访问？是否配置了域名？
9. 帐号密码是否会过期？
10. 是否需要备份，如何恢复？
11. 是否需要接入监控告警？
12. 做过什么变更？

在编写文档时为了提高可读性、准确性还需要注意以下事项：

1. 明确文档是干嘛的，提炼标题、关键字和简介
2. 用词准确，无错别字，无歧义，前后无矛盾，避免模糊用词和模糊的说法
3. 避免隐含的假设，重视默认值

--