stm32和电机开发（从架构图到文档编写）

很多同学不喜欢写文档，总觉得写文档耽误事，影响开发效率。实际上，不一定是那么回事。在实际开发中，编写文档的目的主要是为了厘清自己的思路，在开发代码前把所有的事情都考虑到，防止代码写了一半，需要推倒重来的情形发生。

当然，很多时候编写文档的确是枯燥的，那么有没有什么好的办法，可以让文档编写稍微变得容易一点，答案就是先写架构图。因为文档本身就可以看成是架构图+文字的格式。

1、先编写架构图

架构图是软件的魂。我们拿到软件开发需求后，第一步要做的就是模块拆分、流程抽象和接口设计。这部分可以找一些合适的软件来完成，比如visio、openoffice draw、processon都可以。总之，只要能达到目的就行。比如我们写一个网站，那么就可以画一个简单的流程图，

2、给流程图添加文字

有了流程图，或者是架构图之后，下面要做的就是组织文字来描述这个图形。这个需求可以拆分成哪几个模块，每一个模块的功能的作用是什么，模块和模块之间的关系是什么，常用的框架是什么，用户自己有什么使用习惯，这部分都可以开始写起来了。

很多时候，为了避免枯燥与乏味，在文字编写的过程中需要添加目录、修改历史、面向读者、名词缩略、表格、公式、算法伪代码、参考资料等内容。有了这些内容，就可以一下子让文档变得丰富多才起来。把一件事情说明清楚，可以从不同角度绘制图形，这都是可以的，主要还是为了把问题说明白。

3、重中之重是接口

算法的部分，一般大家都会注意。但是接口，特别是模块的接口、函数的接口、配置参数的接口、数据库的接口、网络的接口，这部分常常会忽略到。现在的软件开发越来越大，很多时候并非一个人就可以完成所有的功能。所以，对不同的人来说，除了了解自己开发模块在整个软件系统中的位置，另外一个部分就是软件接口，或者可以说是模块接口。

模块接口可以分成两部分，第一，模块的输入是什么，需要什么样的参数；第二，模块的输出是什么，模块可以提供给别人什么样的功能。在实际开发的时候，还要注意具体接口采用的是什么技术，是485、ethernet，还是can，这个依赖于具体的环境。

4、文档一定要常看常新

文档写完了，不是说就交差完事了。在后续有新的软件需求提出来，或者发生软件变更的时候，文档更新一定是少不了的。0.1版本、0.2版本，这样软件文档就需要不断被维护和更新下去。时间越长，文档的复用价值就会越来越高，根本不需要每次都推倒重来，因此对应开发的代码被复用的机会也会越来越大。相应开发的软件也会越来越健壮，这些都是会随着时间的推移必然会发生的结果。用一句话说，这就是时间的复利效应吧。