基于准则的结构化决策指南

TPamela Peixinho

帕梅拉·佩希尼奥( T Pamela Peixinho)

Lack of documentation is a huge and old problem in software development. We all know that. We have already complained about the lack of documentation during a software discovery as we also haven’t written documentation of software that we built. Maybe you also asked yourself “what have I done here?” when looking at old software that you have worked on.

文档 L 的ACK是软件开发一个巨大的老问题。我们都知道。我们已经抱怨在软件发现过程中缺少文档，因为我们还没有编写所构建软件的文档。也许您也问自己“我在这里做了什么？” 在查看您使用过的旧软件时。

At QuintoAndar this problem isn’t different. We have a bunch of products, services, flows at the same time that we also have a bunch of people working on them, impacting the same users. So, how can we stay sane in this situation and make sure we're exchanging knowledge?

在QuintoAndar，这个问题没有什么不同。我们同时拥有许多产品，服务和流程，也有一群人在使用它们，从而影响相同的用户。那么，在这种情况下我们如何保持理智，并确保我们交换知识呢？

We have already made a great improvement in adopting the Architectural Decision Record (ADR) concept. We are now creating documentations about our architecture decisions, which is amazing and helps us to get everyone on the same page. But what about our flows, APIs, components, and team decisions during development?

我们在采用体系结构决策记录(ADR)概念方面已经取得了很大的进步。现在，我们正在创建有关我们的体系结构决策的文档，这非常了不起，可以帮助我们使所有人都在同一页面上。但是在开发过程中我们的流程，API，组件和团队决策又如何呢？

Looking at these problems, we can say, and we have already heard: “Our code and tests are our live documentation”. This sentence is completely true! That’s why we should take so much care to build high-quality code. On the other hand, this is not enough.

看着这些问题，我们可以说，我们已经听到： “ 我们的代码和测试是我们的实时文档”。 这句话是完全正确的！这就是为什么我们应该非常注意构建高质量代码的原因。另一方面，这还不够。

We need to know the background, decisions made, and their rationale. Our codebase just shows us a picture of WHAT is running in the software, not WHY, and HOW it was achieved.

我们需要了解背景，做出的决定及其理由。我们的代码库仅向我们展示了软件中正在运行的内容的图片，而不是为什么以及如何实现的图片。

Having all these “not coded” content makes us effective and helps avoid rework in your team during development and help others’ team discoveries. So, with this in mind, we can split the documentation usage in these two moments to get the most of it in each phase: before/during development and after the development.

拥有所有这些“未编码”的内容使我们有效，并有助于避免在开发过程中团队中的返工，并帮助他人发现团队。因此，考虑到这一点，我们可以在这两个时刻将文档使用情况分开，以在每个阶段(在开发之前/期间和开发之后)获得最大的利用。

Before and during development documentation is an important tool of communication and alignment to put all team members on the same page. For example, you and your team may have discussed the feature, decided the data modeling (database and API), but one developer is doing the endpoint and another one is creating the data request to show data in the front-end, how can we make sure that both are looking to the same decision and can work simultaneously? How can we make sure that the person that will test the release will also know the most recent team decision?

在开发之前和开发过程中，文档是将所有团队成员放在同一页面上的重要沟通和协调工具。例如，您和您的团队可能已经讨论了该功能，决定了数据建模(数据库和API)，但是一个开发人员正在执行端点，而另一个开发人员正在创建数据请求以在前端显示数据，我们如何确保两者都期待着相同的决定并且可以同时工作？我们如何确保将要测试发布的人员也知道团队的最新决定？

Creating documentation that records team decisions about what it is currently developing is a simple and easy way to have a great communication tool between all team members even when one of them is not present. So, all of them know the contracts between the endpoints and the front-end because we are always updating the same slice of info in the same document. These updates should be everyone’s responsibility during the team process and a good result is to have great software along with all decisions and descriptions.

创建记录团队当前决策的决策的文档是一种简便的方法，即使在其中一个团队成员都不存在的情况下，也可以在所有团队成员之间拥有出色的沟通工具 。因此，他们所有人都知道端点与前端之间的协定，因为我们总是在同一文档中更新同一条信息。这些更新应该是团队过程中每个人的责任，并且良好的结果是拥有出色的软件以及所有的决策和说明。

Flow to illustrating the documentation process while developing a new feature

After development, the documentation built gains another ton of importance. Now, this document helps us to communicate with the ones that weren’t present or that already forgot. We are creating a tool for our future selves. For example, we need to create a new feature in one of our services using another feature already built by another team. In order to do that, we need to understand:

开发之后 ，所建立的文档变得更加重要。现在，该文档可帮助我们与那些不存在或已被遗忘的文档进行通信。我们正在为未来的自我创造一种工具。例如，我们需要使用另一个团队已经构建的另一个功能在我们的一项服务中创建一个新功能。为此，我们需要了解：

how it was built
它是如何建造的
what service was involved
涉及什么服务
what decisions were made in order to create an accurate flow
为了创建准确的流程做出了哪些决定
what was the rationale for it
这样做的理由是什么
what use cases of this development covers
此开发的用例涵盖了什么
how to test it
如何测试

When you’ve already created unique documentation that contemplates all of it and has links to the other related stuff, it’s really faster to start a new development.

当您已经创建了包含所有内容的独特文档并链接到其他相关材料时，启动新开发的速度确实更快。

It is like time traveling to communicate with the team during the development ⏳

就像在开发过程中花时间与团队沟通⏳

Flow to illustrating the documentation process after the development was completed

Therefore, we can see that communication is a key point to enhance our software development in a scalable and easy to maintain way. As Martin Fowler said in one of his articles:

因此，我们可以看到通信是以可扩展且易于维护的方式增强软件开发的关键点。正如马丁·福勒(Martin Fowler)在他的一篇文章中所说：

Why do we bother with models or documentation? They don’t execute, and our customers pay us for working code, not pretty pictures. We bother with models to communicate.

为什么我们要打扰模型或文档？他们不执行，我们的客户向我们支付工作代码，而不是漂亮的图片。我们为模型沟通而烦恼。

Accordingly, to previous points we can understand the importance of creating documentation, but how can I create documentation that will really be effectively used and do not cost much? How do we avoid over-documentation things that will create more doubts than solutions? Looking to this point we have created the Engineering Doc concept using the Design Doc concept as reference.

相应地，到前面的内容，我们可以理解创建文档的重要性，但是如何创建真正有效使用且成本不高的文档？我们如何避免过度记录文档的问题，而这会带来比解决方案更多的疑问？到此为止，我们已经以“设计文档”概念为参考创建了“工程文档”概念。

记录技术决策 (Documenting Tech Decisions)

In order to centralize all engineering related information of the product development, we have used an engineering doc template to record the team's tech decisions. This template could contain, but not limited to the following topics:

为了集中产品开发的所有工程相关信息，我们使用了工程文档模板来记录团队的技术决策 。该模板可以包含但不限于以下主题：

Introduction
介绍
Product goals/Key results
产品目标/主要成果
Engineering
工程
UX
用户体验
Data engineering
数据工程

Those topics could help the squad to insert decisions and to document what the team has done while creating new products.

这些主题可以帮助团队插入决策并记录团队在创建新产品时所做的工作。

To achieve great results recording decisions, the template doc must be created and maintained by all the people in the squad (from business person to engineering). One thing in common in the document is that it needs to be available and understandable independently of the person’s skills.

为了获得记录决策的出色结果，必须由该团队中的所有人员(从业务人员到工程人员)创建并维护模板doc。该文档中的一个共同点是，该文档需要独立于人员的技能而可用并易于理解 。

In the engineering section, we need to be careful to document tech decisions that do not overlap with automated documentation of software. For example, while developing new APIs we have tools to document technically and automatically endpoints using Swagger. If your service does not have it, use the document as a workaround. So, the engineering doc should be used to centralize all the decisions related to WHY and HOW the product was built in that way.

在工程部分，我们需要小心记录与自动软件记录不重叠的技术决策。例如，在开发新的API时，我们拥有工具来使用Swagger技术上自动地记录端点。如果您的服务没有此服务，请将该文档用作解决方法 。因此，应使用工程文档集中所有与以这种方式构建产品的原因和方式相关的决策。

When developing software in a fast-paced environment, we’ve found that it’s very common to forget important things for example tracking and monitoring. So, the template will guide teams while developing new products, setting anchor points of what matters for your organization. Revisiting this document during all software construction (idealization, coding, delivery, production metrics, etc.) is a good starting point to have up to date and consistent content.

在快节奏的环境中开发软件时，我们发现忘记诸如跟踪和监视之类的重要事情是很普遍的。因此，该模板将在开发新产品时指导团队 ，设置对组织重要的锚点。在所有软件构建过程中(理想化，编码，交付，生产指标等)重新访问该文档是拥有最新内容和一致内容的一个很好的起点。

我们的团队何时应开始新的工程文档？ (When should our team start a new engineering doc?)

Prior to developing a new feature, the project owner (engineer or business person) will probably start a new discovery to understand what we have so far before starting developing. This initial discovery will have information about a microservice, business rule, or a completely new system design. This is the perfect scenario to start the document placing all related information and sharing it with your team.

在开发新功能之前，项目所有者(工程师或业务人员)可能会开始进行新的发现，以了解我们到目前为止在开始开发之前所拥有的知识。最初的发现将包含有关微服务，业务规则或全新系统设计的信息。这是启动文档放置所有相关信息并与您的团队共享的理想方案。

While the new things are coming the team could fill the sections in order to register all events and decisions linking the official documentation for the respective sections. This process was described in the image Flow to illustrating the documentation process above.

随着新事物的到来，团队可以填充各个部分，以便注册所有事件和决策，以链接各个部分的官方文档。该流程在映像流程中进行了描述， 以说明上述文档编制过程 。

文件过多 (Over-documentation)

Therefore, should I write everything in this document?

因此，我应该在本文档中写所有内容吗？

Not exactly. Take care! Worse than not having documentation, is having documentation that nobody will read because it is so over-documented. We need to find the right balance of information. So, always ask yourself if you’re registering important decisions that it’s really necessary for the development and later consultation or just writing buzzwords about your development.

不完全是。 照顾自己！比没有文档更糟糕的是，有文档供任何人阅读，因为文档过多。我们需要找到适当的信息平衡。因此，请始终问自己是否正在注册对于开发和后来的咨询确实必要的重要决策，或者只是为您的开发写下时髦的字眼。

过时的文档 (Outdated Documentation)

So, every time I change something related about this document should I update this doc

因此，每次我更改与此文档相关的内容时，都应该更新此文档

NO! This is not the live documentation. It’s live documentation ONLY during the development process, but after the development, it turns into a “register”, a static document of the team decisions. Imagine that every time we make a decision, we register the decision, we have all logs of the different teams linking each other.

没有！ 这不是实时文档。它仅是在开发过程中的实时文档，但是在开发之后，它变成了“注册”，即团队决策的静态文档。想象一下，每当我们做出决定时，我们都会注册该决定，我们将不同团队的所有日志相互链接。

幕后花絮 (Behind the scenes)

We focused before in documentation as a communication tool, and we want to step back to explain how was our process to achieve it.

我们之前专注于作为交流工具的文档，我们想退后一步来说明实现该过程的过程。

In our team, we were recreating an architecture, and we needed to work at the same time in different services using the same data structure even when it wasn’t there yet.

在我们的团队中，我们正在重新创建一个架构，我们需要使用相同的数据结构同时在不同的服务中工作，即使当时还没有。

Our first problem was no documentation at all, obviously a problem. So, we started creating one document to explain the architecture, another one for the testing scenarios, another that contained the data structure, creating what we called documentation hell

基于准则的结构化决策指南_如何记录团队技术决策的指南相关推荐

机器学习结构化学习模型_生产化机器学习模型
机器学习结构化学习模型 The biggest issue in the life-cycle of ML project isn't to create a good algorithm or to ...
hive编程指南_第三篇|Spark SQL编程指南
在<第二篇|Spark Core编程指南>一文中,对Spark的核心模块进行了讲解.本文将讨论Spark的另外一个重要模块--Spark SQL,Spark SQL是在Shark的基础之上 ...
delphi5开发人员指南_建立开发人员职位的黄金指南
delphi5开发人员指南 Landing a software engineering position can be one of the most difficult obstacles tha ...
openresty完全开发指南_送给你，PBA商业分析指南（全书下载）
商业分析指南简介: 预计在未来的3-5年里, 组织对商业分析师的人才需求会不断增长,PMI职业脉搏调查中有 53%的组织报告有这样的人才需求计划.研究也表明, 一些项目问题将持续困扰着组织, 而这些问 ...
drools规则引擎技术指南_物联网规则引擎技术
物联网应用程序设计与典型的IT解决方案大不相同,因为它将物理操作技术(OT)与传感器.致动器和通信设备连接起来,并将数字信息技术(IT)与数据.分析和工作流连接起来. 在企业环境中,物联网非常复杂,这 ...
selenium初学者指南_如何进化人工智能生活：初学者指南
selenium初学者指南 'Evolving artificial intelligent life' might sound like a grandiose claim from an indi ...
世界卫生组织高血压防治指南_建立对团队和组织的信任的指南
世界卫生组织高血压防治指南我的环球旅行使我对如何在许多不同的背景下(例如拉丁美洲,西非,北非和东南亚)的最佳工作方式有一种感觉. 而且我发现,如果我专注于在所有国家/地区中都扮演重要角色的工作,我可 ...
photoshop脚本指南_如何学习Photoshop的极客指南，第1部分：工具箱
photoshop脚本指南 Photoshop is one of the most intimidating programs for any beginner, but has powerful ...
会议指南二维码生成_包装和准备技术会议的指南
会议指南二维码生成北半球的春天如雨后春笋般涌现,这意味着技术会议季节即将来临. LinuxFest Northwest , OSCON , OpenStack Summit , Write Docs ...

基于准则的结构化决策指南_如何记录团队技术决策的指南