就系统文档征求意见

Question

我有一个评级引擎(基本上是一种算法)，当我开始使用它时，没有正式的文档。我们已经创建了一个功能规范/分解，这是我们的业务级别文档，但是现在我需要一些更技术性的东西(技术规范)。

我很难理解的是，这份文件是什么样子的，它的格式应该是什么，我们应该进入什么层次的细节。

我们正在对所有代码进行注释。我们还有一个叫做Blueprint的粗糙文档，它反映了模型的流程，是用伪代码编写的。该蓝图和模型注释的结合是否足以作为技术规范？

Answer 1

不要仅仅为了它而写评论。注释公共API，注释REGEX表达式，评论一些真正困难的东西(很少遇到所有的框架和工具)。我不认为这能解决你的问题。

为一个不知道你在做什么的人写一份文件。文档应该解释您为什么要这样做，您是如何这样做的，以及如何测试它(验证)。

找一个不知道你在做什么的人。把文件给他们。如果这对他们来说很有意义，那么你已经做得很好了，否则就回到画板上去。