技术文档编写

一直以来，很少会把技术文档这样的事情当作一件重要的事情来处理。

写文档这件事，对于开发者而言是一件费力不讨好的事情，因为绝大部分开发者都并不擅长写文档。

模板

想到这个的第一念头就是找模板，找到的是一份软件需求规格文档，大致看了看，发现这种模板基本没有参考意义。

然后就想到了文档的类型问题，个人是经常写 markdown 的，所以自然就有限考虑了。 事实上很多开发者也确实使用它，可它的问题也很明显，但凡复杂一点 markdown 就有些力不从心。

最常见的就是 docx 文档了，这类文档的问题在于无法与 git 进行配合，有解决方案，但绝对不是一个好的方式。

就工作环境而言，没有办法，只能使用 docx ，因为非技术人员大多不了解所谓的 markdown ，他们能理解的只有 docx。 而且日常接触到的过程中，大部分确实也是 docx。

文档应该怎样

长久以来都在纠结形式，仔细想想，文档的目的是为了让别人能理解如何使用，既然如此不妨从实用性入手。 如果不是商业性质的需要对外发布的文档，那完全可以考虑像很多技术文档一样，写一个 ”快速上手“ 以图文多种表现形式，展示出来。

文档中最重要的部分，就是作者及联系方式，因为文档如果不理解，最后的求助方式应该要指出来，原作者必定是最了解的人了。 仔细想想，经常找一些第三方库的使用文档，很喜欢带有快速上手的文档，因为它足够直白，可以按照文档立刻实操，浅显的体验下使用方式。

思考

我们都想找一个万能模板，可以套用，但最后发现，没有一个模板能够通用。

这大概就是技术文档这么令人头疼的原因吧。 但只要记得一点，文档的意义绝不是一板一眼，让人敬而远之，而是为了可以帮助到其它人，至少技术文档的意义就是为了帮助其它人。

最后，好的文档一定是在不停的交互中产生的，用户反馈，作者修改，共同才能完善文档，有反馈的文档才能变得更好。