GaussDB(DWS)《构建与崩塌之有效的指导文档》

请写一篇有效的指导文档

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

有效

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

指导

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

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

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

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

总结

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

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

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

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

①完整的步骤：

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

②相关工具获取

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

③相关名词解释

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

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

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

EI企业智能 Gauss AP 数据仓库服务 GaussDB(DWS)

版权声明：本文内容由网络用户投稿，版权归原作者所有，本站不拥有其著作权，亦不承担相应法律责任。如果您发现本站中有涉嫌抄袭或描述失实的内容，请联系我们jiasou666@gmail.com 处理，核实后本网站将在24小时内删除侵权内容。