使用文档驱动的设计来指导API的决策
Image of a person writing and working on a computer by Danai via Adobe
一个人在电脑上写作和工作的图片，由Danai通过Adobe制作
As software design evolves, so do the thought processes behind the design decisions we make as engineers. Some of these development practices are widely known and talked about, such as Test-Driven Design, where changes to code are made in programmatic tests before they’re implemented in actual business logic.
随着软件设计的发展，我们作为工程师做出的设计决定背后的思维过程也在不断发展。其中一些开发实践是广为人知和谈论的，例如测试驱动设计，即在实际业务逻辑中实现之前，在程序测试中对代码进行修改。
These design practices are helpful for our future selves and for our teammates, because they help us keep our code well-maintained and easily extendable. How do these practices help external audiences, or audiences that aren’t as technical, understand our code? When designing a new API or making impactful changes to an existing API, a Documentation-Driven Design approach can be helpful in guiding the design decisions you make, too.
这些设计实践对我们未来的自己和我们的队友都很有帮助，因为它们可以帮助我们保持代码的良好维护和易于扩展。这些实践如何帮助外部受众，或那些不那么技术化的受众理解我们的代码？当设计一个新的API或者对现有的API进行有影响的修改时，文档驱动设计的方法也可以帮助指导你的设计决策。
Image by Patrick Tomaso via Unsplash
Documentation-Driven Design (DDD) is the practice of writing your technical documentation first, and then using those docs to steer your eventual code implementation.
文档驱动设计（DDD）是指首先编写技术文档，然后用这些文档来指导最终的代码实现的做法。
All developers want to work with simple APIs. But when the source material that’s driving API design is not simple, we want an API that makes a dense subject easier to understand. This is where DDD is especially helpful because it forces you to think about how an outsider understands and uses your work. Because the crux of DDD is based on thinking through your code as an outsider, it’s also important to know your audience when writing your docs.
所有的开发者都希望使用简单的API工作。但当驱动API设计的源材料并不简单时，我们希望API能使密集的主题更容易理解。这就是DDD特别有帮助的地方，因为它迫使你去思考外人如何理解和使用你的工作。因为DDD的核心是以局外人的身份来思考你的代码，所以在写文档时了解你的听众也很重要。
For many of us at PayPal, our main audience are developers working for merchants to implement ecommerce we...