有关技术文档的一点感想

Posted 2020-06-14

   在IT行业很多的技术人员都不是很注重技术文档，或是没有明白技术文档的重要性。

   大多数的人都觉得文档的撰写，整理，归类是一件很麻烦的事，因而很多的时候为了规避麻烦就避而远之，在做有关文档的工作的时候，能省则省，能简略就简略。很多的程序员在写程序的时候竟然没有注释，很多的编程人员，包括电子工程师，在写程序的时候都没有对程序中重要的变量进行说明，在写函数的时候没有对函数的功能进行描述，没有传入参数，返回参数，以及中间重要变量的说明。

   前一段时间在学习ZigBee，看了人家TI公司Z-Stack协议栈中的代码，感觉那代码是一种艺术，看上去很美观，很有艺术感。基本上每一个函数都进行大量的说明，函数中的参数，变量以及返回参数都进行了详细的说明，看了一下函数的描叙就知道函数的功能，一目了然。

   我承认我也有很多这样的不足之处，但是自己在慢慢的改进，希望以后能克服这样的缺点。

   前一段时间一直在帮老师写那个专利申请书，感觉文档真的很重要。别人了解一个项目也是通过对项目有关的文档阅读而得知，文档撰写或是整理的不好，人家看不懂就出现摸棱两可的感觉，次数多了就会厌烦，人家也不愿意和你合作。在写程序的时候，尤其是程序的代码量较大的时候，一个人基本上无法完成，就必定要找人合作，最后进行程序联调的时候，看不懂别人的程序还是需要自己更多的时间进行解释，最终还是得不偿失。

    做挑战杯有一段时间了，本来想先把实物做好了，至于文档的整理只需要几天时间搞定的。但是后来发现很多东西没有相当，很多人家要求的描叙性文字很欠缺，很多地方需要查找资料，看参考文献，所以后来原本打算3天就搞定的东西，结果拖了一个星期，而且还经常把午休的时间投入，晚上还要忙到11点。结果上周交完报告的时候，人就生病了，回家静养了两天，还是得不偿失。所以以后还是要多多注重文档的整理。

    在此与大家共勉，在文档工作方面再接再厉，做到更好！