项目需求和产品需求_项目需求和你

项目需求和产品需求

介绍(Introduction)

This article isn’t going to be language or framework-specific. It is going to be a high-level discussion of pitfalls in project requirements. I will base this around a project involving merging two similar but not identical datasets and the kinds of issues you can expect. As you may have noticed, I have a pattern in my articles. This article is related to a project I am working on for a customer right now. It is a surprisingly interesting small project to merge two datasets that, to a human reader, contain the same data, formatted differently but to a computer, are entirely different. The incoming dataset is a set of records, one per type of entity within a group, where it is a field on the record. So, you end up with something that looks like call it type 1 data records:

本文不会针对特定语言或特定于框架。 这将是对项目需求陷阱的高层次讨论。 我将以一个项目为基础，该项目涉及合并两个相似但不完全相同的数据集以及可能遇到的问题。 您可能已经注意到，我的文章中有一个模式。 本文与我正在为客户开发的一个项目有关。 合并两个数据集是一个令人惊讶的有趣小项目，对于人类读者来说，这两个数据集包含相同的数据，但格式不同，但计算机却完全不同。 传入数据集是一组记录，一组中每种类型的实体一个，在记录中是一个字段。 因此，您最终得到的东西看起来像是将其称为1类数据记录：

Record
{
  Group : value multiple
   Entity : 
     {
     Complex data with multiple parts here
     }
}
Record
{
   Group: same
   Entity Type 2
   {
    Similar but not identical complex data here.
   }
}
...
Record
{
   Group: same
   Entity Type X
   {
    Similar but not identical complex data here.
   }
}

In general terms, the record has an identifier that groups the complex entities of different types, each with a separate record or number of records into groups. The data structure this is to be turned into is a single record per Group with multiple columns for the complex data. So, something that looks more like this call it type 2 data records:

一般而言，记录具有将不同类型的复杂实体分组的标识符，每个实体具有单独的记录或记录数量成组。 要变成的数据结构是每个组一个记录，其中包含用于复杂数据的多列。 因此，看起来更像这样的东西称为2类数据记录：

Group:
Entity Type 1
   {
   Complex data with multiple parts here
   }
Entity Type 2
   {
   }
Entity Type 3
   {
   }
. . .
Entity type N
   {
   }

So, fewer records, but each record is more complicated. To make the project more interesting, existing data in the dataset with type 2 records must be maintained. Well, kind of maintained, it can be modified by the incoming type 1 records.

因此，记录较少，但是每条记录更加复杂。 为了使项目更加有趣，必须维护数据集中具有类型2记录的现有数据。 好吧，是一种维护，可以通过传入的类型1记录进行修改。

That’s the setup for today’s discussion on the fun with requirements for merging data.

这就是今天讨论合并数据的乐趣的设置。

最重要的 (Most important)

Have requirements written down and agreed to by the customer. Do this, take the time. Don’t skip this step even if the document is an email. Save that email. You will be referencing this document repeatedly while working on the project, no matter how small it might be. I am serious. A requirements document is more important than a design, more important that version control software, more important than what editor you use. If you don’t define the requirements, you don’t know when you are done. If you don’t know when you are done, you don’t get paid. So, for anyone doing freelance or contract work, the requirements document and some communication from the customer saying that it is acceptable are your gold. That’s what you hang your hat on to get paid, and most companies will feel a whole lot better about hiring you if this is the first thing you do when they start talking to you about a project. The good companies have an initial requirements document as part of the project bid documents. Bad companies to work with will refuse to discuss requirements, run from these projects unless they are willing to let you bill time and materials, then go to town. They are idiots.

写下要求并由客户同意。 这样做，花时间。 即使文档是电子邮件，也不要跳过此步骤。 保存该电子邮件。 不管项目多小，您在进行项目时都会反复引用该文档。 我是认真的。 需求文档比设计更重要，比版本控制软件更重要，比您使用的编辑器更重要。 如果您没有定义需求，那么您将不知道何时完成。 如果您不知道何时完成，则不会获得报酬。 因此，对于从事自由职业或合同工作的任何人，需求文件和客户的一些沟通都可以接受，这是您的黄金。 这就是您想要获得报酬的方式，如果这是您开始与您谈论项目时要做的第一件事，那么大多数公司都会对雇用您感到好多了。 好的公司将初始需求文件作为项目投标文件的一部分。 不好的公司将拒绝讨论要求，从这些项目开始运作，除非他们愿意让您花费时间和材料，然后去镇上。 他们是白痴。

Many companies right now are in the position of laying off most, if not all, their IT and software departments. In these cases, it will give the managers who are used to having their software team write these documents a level of comfort to have you write the document and work with them to get the requirements defined. You should not expect to be paid for this work. Consider it an investment in ongoing relationships. Remember, the best customer for a freelancer or contract software engineer is the one that comes looking for you.

现在，许多公司都可以解雇大多数(如果不是全部)IT和软件部门。 在这种情况下，它将使习惯于其软件团队编写这些文档的管理人员可以放心地让您编写文档并与他们一起工作以定义需求。 您不应期望为此工作获得报酬。 认为这是对持续关系的投资。 记住，寻找自由职业者或合同软件工程师的最佳客户是您。

Moral, write requirements documents, get them signed off on by the customer.

道德，写需求文件，让客户签字。

客户不知道 (Customers Don’t Know)

Well, that may be too strong a phrasing, at least in this case, call it customers were unaware. The type two records are defined by the underlying technology chosen by the customer to have fixed numbers of each entity type. I know there are data storage methods that are more flexible, but the specification on data storage of the result was specified. I tried multiple times to suggest other alternatives gently, and the answer was no, they wanted what they wanted, and that was final. So, a fixed number of Entities of a fixed description. Fine, I can work with that. Unfortunately, the customer was unaware that the incoming data ignored those limits, ignored them by 2–3 times for several of the entity types. Fortunately, being an experienced engineer, my intermediate data structures were not inflexible enough to fail when reading excessive data. However, error flags popped to the tune of 200+ errors on a file supposed to produce around 80 records. While not a record number of errors per line of output, it is undoubtedly my record holder for the last five years. After conferring with the customer, it turned out there was yet another field in several of the entity types ignored in the initial definition that defined which of the specific entities needed in the output data. They did know, they didn’t think to tell the software team that the data was available, and I needed to filter it.

好吧，这可能太过措辞了，至少在这种情况下，称其为客户没有意识到。 客户选择的基础技术定义了两个类型的记录，以使每个实体类型具有固定编号。 我知道有一些更灵活的数据存储方法，但是指定了关于结果数据存储的规范。 我尝试了几次以温和地建议其他选择，但答案是否定的，他们想要他们想要的东西，那是最终的决定。 因此，固定描述的实体数量固定。 很好，我可以解决。 不幸的是，客户没有意识到传入的数据忽略了这些限制，对于某些实体类型，它们被忽略了2-3次。 幸运的是，作为一名经验丰富的工程师，我的中间数据结构不那么僵硬，无法在读取过多数据时失败。 但是，错误标记在一个文件中突然弹出200多个错误，该文件应该产生大约80条记录。 虽然不是每行输出错误的记录数目，但无疑是我过去五年的记录保持者。 与客户协商之后，结果发现初始定义中忽略了几种实体类型中的另一个字段，该字段定义了输出数据中需要哪些特定实体。 他们确实知道，他们不打算告诉软件团队数据可用，因此我需要对其进行过滤。

The moral of this bit, even if you think the requirements are pinned down, they aren’t until you ship the software and get paid.

这一点的寓意是，即使您认为要求已被严格限制，也要等到您交付软件并获得报酬后，才可以这样做。

你不是心灵读物 (You aren’t a Mind Reader)

Don’t guess what the customer wants, ever, for any reason. Email, text messages, phone calls, skype, and other communications are too damn easy anymore to leave anything to chance. If you are unsure, ask. When we were writing the requirements, there was a brief exchange about the idea of merging the new data into the existing data. However, nobody talked about how the new data didn’t modify an existing entity. It removed that entity entirely. I thought from the discussions that what was intended was that I delete the old entity, but we hadn’t specifically discussed this case. So, what did I do? I fired off a quick email and worked on something else for the half-hour it took to get the response. In this case, I was correct. Merge really means if the new data reference the Group at all, it will end up looking like the new data at the end.

永远不要因为任何原因猜测客户的需求。 电子邮件，短信，电话，Skype和其他通信实在太容易了，以至于没有任何机会。 如果不确定，请询问。 当我们编写需求时，就将新数据合并到现有数据中的想法进行了简短的交流。 但是，没有人谈论新数据如何不修改现有实体。 它完全删除了该实体。 在讨论中，我认为打算删除我的旧实体，但是我们没有专门讨论这种情况。 那么，我做了什么？ 我发出了一封快速电子邮件，并花了半个小时来处理其他事情，以获得回复。 在这种情况下，我是对的。 合并实际上意味着，如果新数据完全引用了Group，则最终将看起来像新数据。

On the other hand, I discovered two specific entities never discussed in the incoming data. My guess based on the discussions was that these entities were going to become additional types of entity in the final data structure, probably tacked onto the end. In this case, I was utterly wrong. When I sent my quick email, they told me to ignore records of these types. These were not currently interesting, and it would be another project later if they become relevant.

另一方面，我发现传入数据中从未讨论过的两个特定实体。 根据讨论，我的猜测是这些实体将成为最终数据结构中可能会固定在最后的其他类型的实体。 在这种情况下，我完全错了。 当我发送快速电子邮件时，他们告诉我忽略这些类型的记录。 这些目前并不有趣，如果它们变得相关，它将是另一个项目。

Moral, don’t try to be a mind reader if there is any question at all ask.

道德，如果有任何问题要问，请不要试图成为思想读者。

正确的细节 (The Right Detail)

Getting the level of detail correct is a challenging subject. Getting the right level of detail in a requirements document is a judgment call. It depends on the project, the audience, and the subject. Let me give a couple of examples. In the 1990’s I worked in factory automation, putting conveyor control systems into factories and warehouses. These were massive projects that took multiple years and hundreds of people and companies to put together. The requirements document generally ran into the file cabinet size. They defined everything from the type of steel to use for the conveyor supports to what kind of network cable we had to run. The software part of the document usually ran into the thousand-plus pages. Detailing things like the timing maintained for tracking items on the conveyors to what the user interface would contain and what reports we had to generate. So, the detail matched the time and effort put into the projects. If someone was spending hundreds of thousands or millions of dollars putting in an automatic conveyor sortation system, they were going to damn well define down to the last screw and washer what they were getting. When I worked on airport baggage handling systems, the requirements documents filled rooms, not filing cabinets.

使细节水平正确是一个具有挑战性的课题。 在需求文档中获得正确的详细信息级别是一个判断的要求。 这取决于项目，受众和主题。 让我举几个例子。 在1990年代，我从事工厂自动化工作，将输送机控制系统投入工厂和仓库。 这些大型项目耗时数年，数百人和公司共同组成。 需求文件通常会遇到文件柜的大小。 他们定义了所有类型，从用于输送机支撑的钢材类型到我们必须运行的网络电缆。 该文档的软件部分通常会显示成千上万的页面。 详细说明诸如跟踪传送带上的项目所需的时间安排到用户界面将包含的内容以及我们必须生成的报告。 因此，细节与投入项目的时间和精力相匹配。 如果有人花数十万或数百万美元安装自动输送机分拣系统，他们会很想知道最后一个螺丝钉，然后清洗所得到的东西。 当我在机场行李处理系统上工作时，需求文件填满了房间，而不是文件柜。

I am in no way saying you need this level of detail. For my last two projects, I have written about two pages each. Defining what the data input looked like, what transformations I needed to perform, and what the data output is. What specific data storage used was determined by the customer in both cases, but I documented that as well, so we agreed on it. Then we passed the document back and forth between two and four times with tracked changes on, both making changes as needed from phone calls and emails. In the end, the customer sent it back with an email saying that yes, that is what we want you to do — please tell us how much it will cost and how long it will take.

我绝不是说您需要这种详细程度。 对于我的最后两个项目，我分别写了大约两页。 定义数据输入的外观，我需要执行的转换以及数据输出是什么。 在这两种情况下，由客户确定使用哪种特定的数据存储，但是我也对此进行了记录，因此我们对此表示同意。 然后，我们在跟踪的更改之间来回传送文档两次至四次，并根据需要通过电话和电子邮件进行更改。 最后，客户用一封电子邮件将其发送回去，说是的，这就是我们想要您做的-请告诉我们这将花费多少，并且花费多长时间。

So, don’t write over detailed requirements. Write the things you need and only what you need. In many ways, the level of detail from those conveyor control documents was insane and useless. By the time the project was in progress, some of the “required” items were no longer available. Some variances had to be requested because a “standard” steel from twenty years ago is no longer standard, and you can’t buy brackets made in that steel except via special order at ten times the expected price.

因此，请勿覆盖详细要求。 写下您需要的东西，只写下您需要的东西。 在许多方面，这些输送机控制文档中的详细信息级别都是疯狂且无用的。 到项目进行时，一些“必需”项目不再可用。 由于20年前的“标准”钢已不再是标准钢，因此必须提出一些差异，并且除非通过特殊订购才能以预期价格的十倍购买该钢制的支架，否则就无法购买。

Moral, enough detail but not too much.

道德，足够细节，但不要太多。

结论 (Conclusion)

Write requirements documents, especially if you are a freelancer, they may be the difference between getting paid and not. There isn’t much beyond that I can say, even a bad requirements document is better than none. But it is worth your time to learn how to write a good one. I would tell you where I learned, except I learned by reading horrible documents then doing the opposite whenever possible. I wouldn’t recommend this technique, but it is a way to learn.

编写需求文档，尤其是如果您是自由职业者，则可能是获得与否之间的区别。 我无法说的太多了，即使是糟糕的需求文档总比没有好。 但是，值得您花时间学习如何编写出色的文章。 我会告诉你我学到了什么，除了我是通过阅读可怕的文档然后尽可能做相反的事情学到的。 我不推荐这种技术，但这是一种学习的方法。

Good luck, and have fun.

祝好运并玩得开心点。

翻译自: https://medium.com/the-innovation/project-requirements-and-you-d0d2616c00be

项目需求和产品需求