过程:记录更改的规范

Question

一个小小的背景:我在一家相对较小的(<10开发人员)科技公司工作，该公司基本上生产一个单一的产品，该产品不断发展，并被添加到其中。该产品是一种现成的客户机/服务器产品，我们运行服务器，客户端是运行在多种平台(Android、iOS、WinMo等)上的移动应用程序。规范和文档的大部分是在内部Wiki中维护的。

每当我们向客户端应用程序添加新功能或扩展现有功能时，流程大致如下：

1. 一份规范。因为变化是产生的。一般来说，这些规范在细节上非常低，通常只是由几个用户故事组成：“作为一个用户，我想.”
2. 这个特性是在一个平台上实现的。哪个平台往往取决于哪个开发者在当时是最免费的，因为不同的开发人员专门研究不同的平台。
3. 一旦该特性或多或少地在领先平台上完成，它就会被移植到其他平台上。

由于最初的规范是如此的笼统，第二步通常需要做出很多更详细的决策--文件格式、出错时该做什么等等。决策通常是在与项目经理协商之后做出的。

我们面临的问题是，没有真正的过程来确保第二步中的决策能够被记录下来。在一个理想的世界里，我想责任可能落在项目经理身上，但由于他也是一名公司董事，所以坦率地说，他没有时间！

我的问题是:有人能建议我们使用一个或多个过程来确保这些决策被记录下来吗？

说“在做决定的时候更新wiki”是很好的，但是现实世界的考虑因素(时间压力，处理用户支持问题的中断等等)都很好。往往意味着它会被遗忘。

Answer 1

您确实需要“在做出决定时更新wiki”。中断和时间压力不是借口。

毕竟，您需要开发测试用例，对吗？你需要在每个平台上运行这些测试，对吗？那么，测试的依据是什么？是的--那些你没有记录的决定。记录它们，您的测试将变得更好(更容易)，您的产品将保证更高的质量，每个人都很高兴。

Answer 2

将代码文档保存在wiki中的最大问题是，在版本控制方面，wiki的文档非常灵活。

这也是我希望文档尽可能接近代码的原因之一，使用一个友好的文档系统(如rst )，并将代码与代码一起存储在项目存储库中。

我将我关于文档的许多想法归纳到回答中来问什么是科学软件文档的好方法？问题，但它们既适用于商业代码，也适用于科学代码。

我关于高级文档的第三点是最直接相关的，但不要忘记，一旦项目完成，单元测试可能会将您的需求记录为比规范文档更好地实现的需求，因此您可能会更好地根据您已经拥有的内容来指定未来的更改，而不是您最初想要的。

如果您在项目代码存储库中将您的规范作为文档编写，那么如果您将您的代码分支到一个新版本中，那么您也会得到文档的一个分支。在您的示例中，您将启动代码开发的一个新分支，更新规范，然后更新代码。

对于开发人员来说，这一切都是同步的，没有人会看到规范的变化，直到他们准备好将它们合并。

一旦完成了工作(或至少达到了可部署的级别)，规范的更改将与(移植)合并到其他项目中，以及实现这些规范更改的代码中。

有趣的是，如果有合并冲突，合并的行为也会引发合并冲突，就像代码一样。这样，您就可以了解两个开发人员是否以相互不兼容的方式更改了规范。

Answer 3

"The problem we have is that there's no real procedure for making sure the decisions made
 in step 2 actually get documented"

我认为你已经在你的过程中分离出了你可以改进的步骤。在不改变整个组织结构的情况下，我认为，随着规范的发展，必须有人承担维护规范的任务。我知道这是显而易见的，但这将是实现你所面对的最简单的方法。引入一个新的系统将有一些最初的开销，“改变”你做事的方式可能比任何事情都更惹人恼火。

嘿，为什么不把它分配给新来的( FNG)!！哈哈！！

祝好运!