错误 有更多数据可用
Software bugs are like real bugs: No one likes them, but they’re a fact of life, and you need a way to handle them when they show up.
软件错误就像真实的错误：没有人喜欢它们，但是它们是生活中的事实，当它们出现时，您需要一种处理它们的方法。
While engineers are responsible for preventing and addressing software issues, anyone can take part in improving the apps they use by helping to report when things don’t work. Those who work at tech companies especially should recognize that helping to improve the product is part of being a good team player. “If you see something, say something,” as the saying goes.
尽管工程师负责预防和解决软件问题，但是任何人都可以通过帮助报告故障情况来改善他们使用的应用程序。 特别是在科技公司工作的人应该认识到，帮助改善产品是成为优秀团队成员的一部分。 俗话说：“如果你看到什么，就说些什么。”
The problem is, most non-technical folks are never really taught how to communicate with technical teams to get things fixed. This article was written to be the resource I’ve often found myself wanting to be able to forward: a guide on how to be more effective in this particular area of tech partnership.
问题是，大多数非技术人员从未真正学会过如何与技术团队沟通以解决问题。 写这篇文章是我经常发现自己想要转发的资源：有关如何在这个特定的技术合作领域更有效的指南。
I’ll share insights from the engineering perspective to give you an understanding of what makes a good bug report and why. Put these points into practice, and your issues will likely get resolved faster, you’ll have a better relationship with your tech team, and hopefully, we’ll all encounter fewer bugs in the apps we use.
我将从工程的角度分享见解，以使您了解什么是好的bug报告以及原因。 将这些观点付诸实践，您的问题可能会更快地得到解决，与您的技术团队之间将建立更好的关系，并且希望我们在使用的应用程序中遇到的错误更少。
错误程序 (The Bug Process)
The purpose of a bug report is to clearly explain an observed issue and detail the steps taken to produce it so that a technical team can identify its root cause and implement a resolution. A good report is one that helps gets an issue resolved most efficiently. To give you a sense of what this process typically entails at a software company, I’ve summarized a general issue workflow visually:
错误报告的目的是清楚地说明观察到的问题，并详细说明解决问题的步骤，以便技术团队可以确定其根本原因并实施解决方案。 一份好的报告可以帮助您最有效地解决问题。 为了让您大致了解此过程通常在软件公司中所需要执行的工作，我在视觉上总结了一个一般性问题工作流程：
The key takeaway for you, the bug reporter, is that when you submit an issue, you’re creating a task that runs through a multi-step communication flow. Minimizing inefficient loops and stalls in this workflow heavily depends on the information that seeds it. Therefore, the one thing to remember when it comes to reporting bugs is this: The better the quality and quantity of the information you provide, the faster and easier it is to fix the bug.
错误报告者对您来说最重要的一点是，提交问题时，您正在创建一个通过多步通信流运行的任务。 最小化此工作流程中无效的循环和停顿在很大程度上取决于播种它的信息。 因此，在报告错误时要记住的一件事是：提供的信息的质量和数量越好，修复错误的速度就越容易。
Unfortunately, the most common reason for a slowdown in an issue’s resolution is it getting labeled with “needs more info.” Every software engineer has sighed at a bug report with little more insight than “it didn’t work.” Hint: You don’t want your issues falling into these categories.
不幸的是，导致问题解决速度放慢的最常见原因是被贴上“需要更多信息”的标签。 每个软件工程师都对bug报告感到叹为观止，而其洞察力仅是“它没有用”。 提示：您不希望您的问题属于这些类别。
So what information should you, the good software citizen, provide?
那么，好的软件公民您应该提供什么信息？
提供上下文 (Provide Context)
First, provide as much context as possible. Your objective is to assist the investigating engineer, and their first task will be to piece together a clear picture of what happened. To do this, they’ll typically combine your firsthand account of events with additional internal information, such as system logs and source code logic. The context you provide helps quickly connect and correlate between these two sources.
首先，提供尽可能多的上下文。 您的目标是协助调查工程师，他们的首要任务是将发生的一切弄清楚。 为此，他们通常会将事件的第一手资料与其他内部信息(例如系统日志和源代码逻辑)结合起来。 您提供的上下文有助于在这两个源之间快速建立联系和关联。
Some examples of contextual information that’s commonly useful:
一些通常有用的上下文信息示例：
- Account Identifiers — Your account email, username, or organization 帐户标识符-您的帐户电子邮件，用户名或组织
- Time and date — When the incident occurred 时间和日期-事件发生的时间
- Location — A web URL and a description of the app screen you were on 位置-一个Web URL和您所在的应用程序屏幕的描述
- App/Platform — Your web browser, mobile platform, or operating system 应用程序/平台-您的Web浏览器，移动平台或操作系统
- Version — The version of the software you’re using 版本-您使用的软件的版本
You’ll also want to provide qualitative context about the issue you’re encountering, as a fair amount of reported “bugs” turn out not to be technical issues at all. Sometimes software works exactly as it was intended, but the behavior differs from what you, the user, expected. These “user error” scenarios indicate a communication or UX shortcoming in the product, and require design thinking to address. Therefore, when reporting something you believe to be an issue, include context on what you were trying to accomplish and what you expected to happen. This will help inform product owners in cases when an appropriate solution needs to be designed, not just implemented.
您还需要提供有关所遇到问题的定性背景信息，因为相当多的报告“错误”根本不是技术问题。 有时，软件可以完全按预期运行，但是行为与您，用户所期望的不同。 这些“用户错误”场景指示产品中的通信或UX缺陷，并且需要设计思想来解决。 因此，在报告您认为是问题的内容时，请包括有关您要完成的任务和预期发生的事情的上下文。 如果需要设计适当的解决方案，而不仅仅是实施合适的解决方案，这将有助于通知产品所有者。
过度沟通 (Overcommunicate)
Describe the issue you’re encountering by being as specific and detailed as possible. Seriously, overcommunicate. A good target is to try not to get asked for follow-up information on an issue by providing as much as you can up front. The higher fidelity you can make your descriptions, the more engineers have to work with. Pictures are worth a thousand words here, so include screenshots and screen recordings if you can.
尽可能具体和详细地描述您遇到的问题。 认真地，过度沟通。 一个不错的目标是通过尽可能多地提供尽可能多的信息，以尽量避免被要求提供有关该问题的后续信息。 您可以进行描述的保真度越高，则与之合作的工程师就越多。 图片在这里值一千个字，因此，请尽可能包括屏幕截图和屏幕录像。
Consider a user’s hypothetical bug report for a ride-share app: “I’m unable to take a trip.” As an engineer seeing this, I’d have a slew of questions I’d need to ask the submitter. Are you unable to sign in? Does the app crash when you start it? Are you able to take trips in some cases but not others? What error message do you see when this happens? The answer to each of these questions has major implications on where the problem lies, the urgency of the issue, and how to proceed with investigating.
考虑用户对乘车共享应用的假设错误报告：“我无法旅行。” 正如工程师所看到的那样，我有很多问题要问提交者。 您无法登录吗？ 应用启动时会崩溃吗？ 在某些情况下您可以旅行吗？ 发生这种情况时，您会看到什么错误消息？ 这些问题中的每一个的答案都对问题所在，问题的紧迫性以及如何进行调查产生重大影响。
To give you some more insight behind the engineering curtain: a majority of software bugs occur due to the release of new updates, and therefore solving an issue is often first a hunt for recent suspicious code changes. Contextual information and clear descriptions help narrow the search down to potential suspected areas. For example, if you’re having trouble changing billing settings on a mobile app, an engineer aware of a recent migration in the payment systems might jump straight to that section of the codebase, verifying your report against changes in the relevant timeframe.
为了让您有更多了解工程技术的知识：大多数软件错误是由于新更新的发布而发生的，因此解决问题通常首先是寻找最近可疑的代码更改。 上下文信息和清晰的描述有助于将搜索范围缩小到潜在的可疑区域。 例如，如果您在更改移动应用程序上的结算设置时遇到麻烦，那么工程师会意识到支付系统中的最新迁移情况，可能会直接跳到代码库的该部分，从而根据相关时间范围的变化来验证报告。
By providing context (the “who, what, when, where, why”) and specific, detailed information about your issue, you help engineers to better triangulate the source of the problem you’re experiencing.
通过提供有关您问题的上下文(“谁，什么，什么时间，什么地方，为什么”)以及特定的详细信息，您可以帮助工程师更好地确定所遇到问题的根源。
详细说明复制步骤 (Detail the Steps to Reproduce)
While context is helpful, the most valuable information you can provide is a clear set of steps to consistently reproduce the observed issue. This isn’t always easy or possible, but you as the person experiencing the bug are in the best position to obtain this key information.
尽管上下文有帮助，但您可以提供的最有价值的信息是一组清晰的步骤，以一致地重现观察到的问题。 这并非总是容易或不可能的，但是作为错误的人，您最有可能获取此关键信息。
When you encounter a software bug, think of yourself as having taken an unexpected turn off the main path in a product’s figurative forest. Most bugs don’t hide in plain sight because if they were obvious, they’d likely have been caught before reaching the wild. Software issues typically manifest because of an unexpected sequence of actions or a specific combination of conditions — what engineers call edge cases. Each bug you encounter appears as a result of the specific steps you took, at a point in time, under a set of unique conditions that applied to you. Recreating all these factors to consistently arrive back at this spot is the key challenge; your goal is to provide instructions that will help a bug catcher do so.
当您遇到软件错误时，请想像自己是意外地关闭了产品形象森林中的主要路径。 大多数错误不会隐藏在视线中，因为如果它们很明显，很可能是在被发现之前就被捕获了。 软件问题通常是由于意外的动作序列或特定的条件组合(工程师称之为边缘情况)而显现的。 您遇到的每个错误都是由于您在适用于您的一组独特条件下在某个时间点采取的特定步骤而导致的。 重建所有这些因素以始终如一地回到这一点是关键的挑战。 您的目标是提供说明，以帮助Bug捕获程序这样做。
The reason that these steps to “repro” an issue are so valuable is that the key to cracking a bug is figuring out exactly why the failure mode is occurring. Without understanding why an issue exists, engineers can’t effectively reason about and implement a solution. Once an engineer can consistently reproduce a bug, the battle is often half won, as the root cause is significantly easier to deduce when an error can be repeatedly observed. Theories can be tested by tweaking conditions, repeating the steps, and observing results. The critical thinking involved in this part of the process is usually the core work of solving an issue, as writing a code fix is a relatively easier task.
这些“重现”问题的步骤之所以如此有价值的原因在于，破解错误的关键是确切地找出发生故障模式的原因。 如果不了解为什么会存在问题，工程师就无法有效地推理和实施解决方案。 一旦工程师能够始终如一地重现错误，那么通常就只能赢得一半的胜利，因为当可以重复观察到错误时，根本原因就很容易得出。 可以通过调整条件，重复步骤和观察结果来检验理论。 该过程的这一部分所涉及的批判性思维通常是解决问题的核心工作，因为编写代码修正是相对容易的任务。
Providing clear, specific steps to help engineers see an issue for themselves will dramatically increase the speed at which your bugs are caught. So the next time you encounter a bug, pause, make a detailed observation of your context and do your best to retrace and document the steps you took to get there.
提供清晰，具体的步骤来帮助工程师自己解决问题，将大大提高捕获错误的速度。 因此，下次遇到错误时，请暂停一下，仔细观察您的上下文，并尽最大努力来追溯和记录为达到此目的而采取的步骤。
交流技巧 (Communication Tips)
In addition to describing what went wrong, you should communicate the impact an issue has on your ability to use the product. Describe what tasks you weren’t able to accomplish, the frequency and severity of the issue, and whether you were able to find a workaround. This informs product owners who need to prioritize your issue against the total backlog of work. Note that exaggerating your issue’s severity in hopes of expediting a fix isn’t particularly helpful to the objective reviewer, and avoiding hyperbole gives more credibility to your requests as a whole.
除了描述出了什么问题之外，您还应该传达问题对您使用产品的能力的影响。 描述您无法完成的任务，问题的频率和严重性以及是否能够找到解决方法。 这将通知需要将您的问题优先于总积压工作的产品所有者。 请注意，夸大问题的严重性以希望加快修复速度，这对客观审阅者并没有特别的帮助，而避免过分夸张则可以总体上提高您的请求的可信度。
Another recommendation is to clearly separate your theories about why an issue occurs from objective, factual observations. Your hypotheses can be helpful, but they’ll always be conjecture as you can’t see the source of truth in the underlying systems. The risk of mixing these in with the facts is simply that you might confuse or mislead engineers. While developers can usually filter out extraneous information, they’re still susceptible to getting sidetracked into investigating false leads. Therefore, you can include your prognoses, but call them out as theories separate from the observed symptoms. Avoid sending engineers on wild goose chases.
另一个建议是将有关问题发生原因的理论与客观的事实观察清楚地区分开。 您的假设可能会有所帮助，但由于您看不到底层系统的真相，因此它们始终是猜测。 将这些与事实相混淆的风险仅仅是因为您可能会混淆或误导工程师。 尽管开发人员通常可以过滤掉无关的信息，但他们仍然容易被误导去调查错误的线索。 因此，您可以包括您的预后，但应将其与理论上与所观察到的症状分开，以区别对待。 避免派遣工程师追赶野鹅。
Lastly, a quick note on tone. No one likes it when things don’t work, and feeling annoyed while reporting an issue you’ve just experienced is completely understandable. Like any customer support request, however, keeping a courteous tone will serve everyone best here. For the responsible technical team, having mistakes labeled and assigned is usually humbling enough without the extra attitude. When it comes to software bugs, the old adage “you catch more flies with honey than with vinegar” still applies well.
最后，简要说明音调。 没有人会在事情不正常时喜欢它，并且在报告您刚刚遇到的问题时感到烦恼是完全可以理解的。 像任何客户支持要求一样，保持礼貌的态度将在这里为每个人提供最佳服务。 对于负责的技术团队而言，通常在没有额外态度的情况下将错误标记并分配给他们很容易。 关于软件错误，古老的格言是“用蜂蜜比用醋捕获更多的苍蝇”仍然适用。
总结 (Concluding)
Technology and team processes are of course constantly improving to better detect and prevent software issues from impacting users in the first place. But as long as we have complex technical systems designed by fallible humans under time constraints, we can expect bugs to exist. And these bugs will be encountered and handled by people who need to communicate with each other.
当然，技术和团队流程也在不断改进，以便首先更好地检测和防止软件问题影响用户。 但是，只要我们拥有在时间限制下由易犯错误的人员设计的复杂技术系统，我们就可以期望存在错误。 这些错误将由需要彼此通信的人员遇到和处理。
While most of our discussions on improving software revolve around computer systems, all software is also fundamentally intertwined with a human system comprised of the people who care about its creation and utility. As a user, you can choose to be an active, helpful agent — an antibody in the product’s immune system. My hope is that reading this article will contribute in some small way to that choice. Because, especially in this day and age, a world with fewer bugs — that’s something we can all get behind.
尽管我们大多数有关改进软件的讨论都围绕计算机系统展开，但所有软件也从根本上与由关心软件开发和实用性的人们组成的人类系统交织在一起。 作为用户，您可以选择成为一种活跃的，有用的药物-产品免疫系统中的抗体。 我希望阅读本文将以较小的方式为该选择做出贡献。 因为，尤其是在当今时代，一个bug更少的世界—我们都可以落后。
附录：错误报告备忘单 (Appendix: A Bug Reporting Cheatsheet)
Here’s a quick reference for bug reporting you can customize for yourself or your team:
这是错误报告的快速参考，您可以为自己或您的团队自定义错误报告：
记得 (Remember)
- Be detailed and specific. Over-communicate. 详细而具体。 沟通过度。
- Separate out your theories from observations. 从观察中分离出您的理论。
- Keep a courteous tone. 保持礼貌。
提供背景 (Provide context)
- “Who, what, when, where, why” “谁，什么，什么时候，什么地方，为什么”
- Account identifiers, date and time, location 帐户标识符，日期和时间，位置
- Include screenshots/recordings 包括屏幕截图/记录
描述 (Describe)
- What you did 你做了什么
- What you expected to happen 你期望发生什么
- What actually happened 实际发生了什么
- Provide steps to consistently reproduce the issue 提供步骤以一致地重现该问题
影响力 (Impact)
- How is this impacting your usage of the product? 这如何影响您对产品的使用？
- Did you find a workaround? 您找到解决方法了吗？
翻译自: https://medium.com/better-programming/a-guide-to-better-bug-reporting-9cd81b17351f
错误 有更多数据可用
146
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
