请写一篇有效的指导文档

    为了让大家尽快明白，我到底想表达什么。先提取两个标题中的关键词，“有效”和“指导”。

有效

    此处的有效，指通过阅读和理解文档中的方法和步骤，可以起码依样画葫芦的把文档中的事情做起来，哪怕只是最基础的程度。(文档通过文字描述和图片等等方式，传递完整的逻辑链给读者)

指导

    专门说明是指导类的文档，是为了避免无效的讨论。因为文档的类型五花八门，有些文档的目的，只是宏观的讨论如何去计划或者一件事情，而不包含具体的执行步骤，比如一些思路分享或者科普类的文档。

    有了上面两点的认识基础，我们再来讨论，导致一篇指导文档“无效”最常见的原因。

文档的作者和阅读者缺少共同的认知空间，导致读者无法获得完整的逻辑链

    文档的作者，因为对于所描述事情的熟悉，经常会把一些工具和专有名词的含义视为默认大家都会的东西。这个问题，是导致指导文档无效最多的原因。也许作者本人还会觉得非常冤枉，：“我已经写的很清楚了呀，大家不看还跑来问我，我也没办法”。

    所以，对于操作中涉及的工具，即使不做对应的讲解，也提供个可以自行学习和下载的链接吧。我甚至遇到过，用到的工具有十几个版本，文档中既不提供工具，也不告诉你来源和版本的选择。这种好像掌握了一条知识的逻辑链，但偏偏缺少几个重要的环节，导致事情无法做下去的时候，真的是让人有种“蜀道难，难于上青天”的感叹！  

    其次，对于文档中的一些专有名词，尤其是英文字母缩写的名词，就算不做详细的解释，起码给个英文全称，让人有处可查吧。

总结

    能够为了达成目标，耐心去寻找和阅读文档的人，起码都是有一定的求知欲和学习能力的人。不需要大家把饭喂到嘴边，但起码给条”求生之路“吧，至少要提供以下三点信息。

        ①关系到构建完整认知逻辑的名词，给出一定的解释；

        ②操作中用到的工具，起码给个获取方式和应用版本的建议；

        ③完成目标行为的完整步骤；

    最后还是举个例子，比如一篇从windows桌面提交代码到代码仓的操作指导文档，至少包含以下信息。

         ①完整的步骤：

        在代码目录下打开git bash->git add目标文件->git commit提交请求->git push推送到个人分支->在个人分支中对比和主库的差异，打开merge->通过各项流水线检      查后，发送链接给评审人员评审->符合合入条件后，找合并人合入merge

        ②相关工具获取

        git工具可以从华为工具云下载，无版本要求。直接默认步骤安装后，参考xxxxxxx进行和代码仓库的鉴权配置。

        ③相关名词解释

        git xxx为打开git bash后的具体操作指令，具体操作示例如下图所示，xxxx

        评审人员和合并人，会在打开的merge链接中显示，如下图所示,xxxx

    当然，上面的例子不一定完全准确，比如一些名词解释，可能通过描述时的截图就能说明了，不需要单独去做说明。但是不管以什么形式呈现，这三点信息是一定要提供的。也就是说，指导文档，要想达到目的：需要告诉读者在理解某个逻辑后，使用什么工具，按照什么步骤来完成某件事情。一定不要让关键细节的缺少，导致逻辑链断掉！