编写技术规范的过程

我有点担心这可能是重复的,但我搜索了网站,我能找到的每个问题似乎都更侧重于功能规范而不是技术规范.

我在寻找如何传达信息如何事情应该做的,而不是什么应该做的事.我认为在最简单的层面上,我正在寻找最好的方法来帮助向初级编码员解释实现功能规范的正确方法.

关于文档的大多数答案似乎都假设,一旦给出详细的需求列表,开发人员就会知道实现它的最佳方式,而且我倾向于发现通常情况并非如此.到目前为止我发现的最好的资源似乎是史蒂夫麦康奈尔的10*软件开发,但我想知道是否有其他人有一些有用的答案.

我将建议从无痛功能规范开始阅读Joel的系列- 第1部分:为什么要打扰？ 他甚至可以链接到Project Aardark规范(现在是Copilot),您可以下载并阅读它作为制定良好规范的示例.

但有一点:您在帖子中提到了技术和功能规范.有区别.

你正在谈论它似乎的编码标准问题(以及).

就个人而言,我赞成基于Wiki的纯技术设计文档方法.开发人员jsut不喜欢编写大型Word文档.Wiki允许您编写内容,协作,插入类图或任何适当的内容.

我发现了一些关于这方面的更多信息,就像Joel所写的关于技术与功能规范的这个主题:

我的想法是,你只是不编写涵盖应用程序整个功能的"技术规范"......这就是功能规范的用途.一旦你有了一个完整的功能规范,唯一要记录的是内部架构和特定算法的点,这些点是(a)完全不可见(在封面下)和(b)功能规范不够明显.

所以技术规范结束了.在这里你可能会或可能不会有一些关于小主题的技术文章:

和

请记住,如果您正在谈论的任何内容影响用户界面甚至是您正在构建的事物的行为,那么它就属于功能规范......所以留给技术规范的所有东西都是程序员感兴趣的东西.事实上,很多东西在评论中可能是最好的,所以最多,你应该有一些关于算法等主题的短篇文章 - 当你需要思考时,你可以根据需要写这些文章.为未来的程序员设计或记录"大图",这样他们就不必弄清楚你的代码想要完成什么.

它比我更有说服力地描述它.

有趣的是,我认为这个问题会得到许多有争议的答案,相反,我们得到的建议是,编码标准将解决问题或让开发人员继续使用它就是答案.从这个问题来看,我认为关键在于我们正在谈论初级编码员,当你开始从功能规范到完成代码的巨大跳跃时,我们都知道有不止一种方法可以做到这一点.

我的方法是采用系统的一个特定部分,即执行所有技术层 - DB,UI,Web服务,记录应该如何实现,可能使用类图,可能只是建议特定的库和方法.通过这种方式,您的技术规范不会太大,称赞和扩展架构文档(如果您不需要太多doco,可以作为项目符号列表).

然后团队可以完全实现系统的垂直切片,这有很多优点,你可以尽早构建和发布一个小片,体系结构得到证明,迭代0的东西(源代码控制,版本控制,构建)都被运用 - 它只是这样做的方式.