如何建设性地阅读规格说明书

原文：https://medium.com/hackernoon/how-to-constructively-read-a-spec-fac917f58893

当你第一次想到它的时候，阅读一个规范并不是一件听起来应该如此复杂的事情。事实上，以错误的方式阅读规范是一个非常简单的过程:

以错误的方式阅读规范

从头到尾读一遍(或者如果你懒，就浏览一下，或者如果你真的懒，就点击 tldr，然后就此打住)
你完了

如果当你阅读一个规范时你所做的只是阅读它，那么除非这个规范已经很完美了，否则你的阅读并没有帮助规范变得更好。虽然获取规格说明书想要传达的知识总是阅读规格说明书的主要目标，但是额外的主要目标应该总是提高规格说明书的质量。(需要明确的是:提高一个规范的质量本身并不是目的；相反，拥有高质量的规格是执行任何重要项目的基本部分。

那么什么是质量规格？

很高兴你问了！质量规范将完成以下工作:

清楚地陈述正在解决的问题
清楚地定义功能级别上的期望结果(以及技术解决方案，如果已知的话)

从最简单的形式来看，这才是真正的原因。当然，那是一个非常高级的定义。为了实现这些目标，许多因素开始发挥作用:

提供正在解决的问题的背景
给出解决方案的理由和论据(可能探索替代方案)
定义重要的术语和概念
分解解决方案需要实现的方式(总是需要完成，但是可能会根据这是技术规范还是功能规范，以及受众是谁而采取不同的形式)
定义成功标准
在适当的地方，给出用户故事
通篇使用语言，促进清晰和简洁，同时避免冗余和混乱的语言

那么，如果这些是质量规范的组成部分，那么有哪些因素会降低质量规范实现其目标的有效性呢？

缺乏背景/介绍
正在解决的问题定义不明确
解决方案缺乏、定义不清或理由不充分。缺乏对适当的替代方案的探索。
关键术语和概念的定义含糊不清或缺失
要实施的解决方案缺乏或不完整。细分可以存在，但可能不会深入到更复杂问题所需的细节层次。
缺少或不完整的成功标准
规范细节中的内部矛盾或多余/混乱的语言(在任何部分中或之间)

因此，以正确的方式阅读规范意味着…

…带着批判的眼光阅读，同时有以下目标:

引起注意，澄清并修正任何可能降低规范有效性的因素
鼓励规范的所有成功因素

就这么简单:-)

相信你自己

当然，这样一来，阅读规格说明书就从一项容易执行的被动任务变成了一项复杂的工作。这是世界上最容易的事情，回到阅读规范的简单(和无效)的方式。在这样做之前，有一些事情要记住:

一句一句来

像任何大型任务(包括项目本身的执行)一样，当你一次做一点时，它更容易实现。阅读摘要，然后是问题定义、解决方案摘要、故障等。在浏览过程中，寻找那些缺失的、矛盾的、定义不清的边缘案例等——当你看到它们时，写下评论或提出编辑建议。如果有不清楚的地方，请写下评论或提出修改建议。然后继续前进。一次一段。

你的意见很重要&没有愚蠢的问题/评论

你被雇佣或选择在这个项目/团队中工作是有原因的:因为你的观点、技能和知识受到尊重和重视，你的投入是人们感兴趣的。否则你就不会被抄袭，不会被雇佣，也不会有人征求你的意见。因此，如果你在一个规范中看到一些需要注意的地方，那么你有责任对其进行评论。

通常，人们在阅读规范时会有问题，并在提出论点时决定不离开它们:如果这是一个需要问的问题，那么肯定会有其他人问它(因为没有其他人问，所以这是一个明显的问题，只会突出我自己想象的不足)。不要让冒名顶替综合症把你引入这个陷阱。你要说的话有的价值，别人想听。

您对规格的想法和输入确实会产生影响

即使是添加一个丢失的逗号，引起对一个冗余的注意，指出我们的一个微小的不一致，或者询问一个看似牵强的边缘案例——每一点都有所不同。不要低估这一点，也不要以此为借口忽略需要注意的细节。

假设你是唯一一个真正阅读说明书的人。你可以通过仔细阅读并以一种建设性的方式让别人知道你的想法来做出很大的改变。

规范的作者也起着关键的作用

当然，评论和建议只有成为变革和改进的催化剂才有价值。由规范的作者或管理者来审查所有的变更，并在适当的时候使用它们来更新规范。

需要记住的一些重要事项:

这不是针对个人的

如果评论和建议是根据规范提出的，这并不是针对作者。每一个规范在其初稿之后都是不完美的。完善一个规范并使之成为一个更有效的项目执行工具是一个团队的努力。评论和建议仅仅是这种合作的表现形式。当然，评论和建议应该总是相对于内容而言，绝对不应该以任何攻击性的方式提出。只要每个人都认同这些目标，这就不是问题。

如果一个评论或建议没有导致改变，那么它就从来没有真正发生过

经常有人会对某个规范发表评论或提出问题。规范作者将对评论做出回应。也许会有一个来回，几个回合。然后看到问题已经回答了，spec 作者会删除评论而不做其他任何事情。

这是一个的错误。

如果一个人对某个建议有疑问或评论，那么这意味着规范中的某些内容不清楚，需要澄清。即使这个问题的答案是“不，这不是我们要做的改变”，这也是事实。很可能其他人也会有同样的问题(可能不会像你一样认真阅读规范)。解决一个注释而不改变规范或留下一些东西来解决最初的问题，会使它看起来好像从来没有做过注释。即使是最初参与评论交流的人也很难回忆起细节，即使过了一会儿也是如此，当然，那些从未见过最初交流的人也不会意识到任何好处。

我们所说的变化不一定是本质上的重大变化。通常，只需要一个脚注或附加说明，或者几句澄清性的语言，就可以留下以前讨论的有意义的遗迹。然而，当一个规范向它的最终状态靠近时，这些都是规范发展的重要部分，并将为未来的读者和消费者引入一个额外的清晰层次。

最后的想法

大多数开发人员讨厌(或者至少非常不喜欢)编写规范。它们写起来并不有趣。它们读起来一点也不有趣。许多人认为他们是不可避免的祸害，因此在继续从事更“有成效的工作”之前，尽可能给他们最少的时间和精力。

我也真的不喜欢写规格。我找到了各种理由不去做它们，并且拖延了相当长的时间。但是这些年来，我逐渐认识到，如果不预先投入必要的时间和精力到规范编写过程中，按时和按预算完成一个复杂的项目，满足利益相关者交付高质量产品的功能期望是极其困难的(如果不是不可能的话)。我希望在读到这里之后(为此我真诚地感谢你),通过你的努力和关注，你所接触的下一个规范会以一个更好的状态结束。

像任何规范一样，这个文档是一个正在进行的工作。非常欢迎任何关于如何改进的想法、意见或建议。

如果您觉得这里的想法有用，您可能还想看看本系列的其他文章: