proofreading

docs/index.html

@@ -148,8 +148,8 @@
 <li><a href="API.en.html#api-product-kpi">Chapter 56. API Key Performance Indicators</a></li>
 <li><a href="API.en.html#api-product-antifraud">Chapter 57. Identifying Users and Preventing Fraud</a></li>
 <li><a href="API.en.html#api-product-tos-violations">Chapter 58. The Technical Means of Preventing ToS Violations</a></li>
-<li><a href="API.en.html#api-product-customer-support">Chapter 59. Supporting customers</a></li>
-<li><a href="API.en.html#api-product-documentation">Chapter 60. The Documentation</a></li>
+<li><a href="API.en.html#api-product-customer-support">Chapter 59. Supporting Customers</a></li>
+<li><a href="API.en.html#api-product-documentation">Chapter 60. Documentation</a></li>
 <li><a href="API.en.html#api-product-testing">Chapter 61. Testing Environments</a></li>
 <li><a href="API.en.html#api-product-expectations">Chapter 62. Managing Expectations</a></li>
                             </ul>

src/en/clean-copy/07-Section VI. The API Product/10.md

@@ -1,41 +1,43 @@
-### [Supporting customers][api-product-customer-support]
+### [Supporting Customers][api-product-customer-support]
 
-From banning users, let's change the topic to supporting them. First of all, an important remark: when we talk about supporting API customers, we mean helping developers and to some extent business partners. End users seldom interact with APIs directly, with an exception of several non-standard cases:
+Let's shift our focus from banning users to supporting them. First and foremost, it's essential to clarify that when we discuss supporting API customers, we are referring to aiding developers and to some extent business partners. End users rarely directly interact with APIs directly, except for a few non-standard cases:
 
-  1. If you can't reach partners that are using the API incorrectly, you might have to display errors that end users can see. This might happen if the API was provided for free and with minimum partner identification requirements while in the growth phase, and then the conditions changed (a popular API version is no longer supported or became paid).
+  1. If the API vendor can not reach partners who are using the API incorrectly, it might have to display errors that end users can see. This situation might arise if the API was initially provided for free with minimal partner identification requirements during the growth phase, and then the conditions changed (such as a popular API version no longer being supported or becoming a paid service).
 
-  2. If the API vendor cannot reproduce some problem and has to reach out end users to get additional diagnostics.
+  2. If the API vendor cannot reproduce a problem and needs to reach out end users to gather additional diagnostics.
 
-  3. If the API is used to gather UGC content.
+  3. If the API is used to collect UGC content.
 
-The first two cases are actually consequences of product-wise or technical flaws in the API development, and they should be avoided. The third case differs little from supporting end users of the UGC service itself.
+The first two cases are, in fact, consequences of product or technical flaws in API development and they should be avoided. The third case differs little from supporting end users of the UGC service itself.
 
-If we talk about supporting partners, it's revolving around two major topics:
-  * Legal and administrative support with regard to the terms of service and the SLA (and that's usually about responding to business owners' inquiries)
-  * Helping developers with technical issues.
+When discussing support for partners, it revolves around two major topics:
+  * Legal and administrative support regarding the terms of service and the SLA. This typically involves responding to inquiries from business owners.
+  * Assisting developers with technical issues.
 
-The former is of course extremely important for any healthy service (including APIs) but again bears little API-related specifics. In the context of this book, we are much more interested in the latter.
+While the former is undoubtedly crucial for any healthy service including APIs, it bears little API-related specifics. In the context of this book, our primary focus is on the latter.
 
-As an API is a program product, developers will be in fact asking how this specific piece of code that they have written works. This fact raises the level of required customer support staff members' expertise quite high as you need a software engineer to read the code and understand the problem. But this is but half of the problem; another half is, as we have mentioned in the previous chapters, that most of these questions will be asked by inexperienced or amateur developers. In a case of a popular API, it means that 9 out of 10 inquiries *will not be about the API*. Less skilled developers lack language knowledge, their experience with the platform is fragmented, and they can't properly formulate their problem (and therefore search for an answer on the Internet before contacting support; though, let us be honest, they usually don't even try).
+As an API is a product for developers, customer will, in fact, inquire about how this specific piece of code that they have written works. This fact raises the level of expertise required among customer support staff quite high as you need a software engineer to read the code and understand the problem. But this is only half of the problem; another half is, as we have mentioned in previous chapters, that most of these questions will be asked by inexperienced or amateur developers. In the case of a popular API, it means that 9 out of 10 inquiries *will not be about the API*. Less skilled developers lack language knowledge, have fragmented experience with the platform, and struggle to articulate their problems effectively (and therefore search for an answer on the Internet before contacting support, although, let's be honest, they usually don't even try).
 
-There are several options for tackling these issues:
+There are several options for addressing these issues:
 
-  1. The most user-friendly scenario is hiring people with basic technical skills as the first line of support. These employees must possess enough expertise in understanding how the API works to be able to identify those unrelated questions and respond to them according to some FAQ, point out to a relevant external resource (let's say, the support service of the OS or the community forum of the programming language) if the problem is not related to the API itself, and redirect relevant issues to the API developers.
+  1. The most user-friendly scenario is to hire individuals with basic technical skills for the first line of support. These employees must possess sufficient expertise in understanding how the API works to identify unrelated questions and respond to them with corresponding FAQs. They should also be capable of pointing users toward external resources, such as the OS support service or the community forum for the programming language, if the problem is not about the API itself, and redirect relevant issues to the API developers.
 
-  2. The inverse scenario: partners must pay for technical support, and it's the API developers who answer the questions. It doesn't actually make a significant difference in terms of the quality of the issues (it's still mostly inexperienced developers who can't solve the problem on their own; you will just cut off those who can't afford paid support) but at least you won't have a hiring problem as you might allow yourself the luxury of having engineers for the first line of support.
+  2. The inverse scenario requires partners to pay for technical support, with API developers responsible for answering questions. While this approach doesn't significantly impact the quality of inquiries (as it still primarily involves inexperienced developers who can't solve problems independently), it eliminates hiring challenges. This allows for the luxury of having engineers handle first-line support.
 
-  3. Partly (or, sometimes, fully) the developer community might help with solving the amateur problems (see the “[Communicating with Developers](#api-product-devrel)” chapter). Usually, community members are pretty capable of answering those questions, especially if moderators help them.
+  3. In some cases, the developer community, either partially or fully, can assist in resolving amateur problems (see the “[Communicating with Developers](#api-product-devrel)” chapter). Community members are often capable of answering these questions, especially with the assistance of moderators.
 
-Importantly, whatever options you choose, it's still the API developers in the second line of support simply because only they can fully understand the problem and the partners' code. That implies two important consequences:
+Importantly, regardless of the chosen option, API developers must handle second-line support because only they can fully understand the problems and the partners' code. That implies two important consequences:
 
-  1. You must take into account working with inquiries while planning the API development team time. Reading unfamiliar code and remote debugging are very hard and exhausting tasks. The more functionality you expose and the more platforms you support, the more load is put on the team in terms of dealing with support tickets.
+  1. You must take into account working with inquiries when planning the API development team's time. Reading unfamiliar code and remote debugging are challenging and exhausting tasks. The more functionality you expose and the more platforms you support, the heavier the load on the team in terms of dealing with support tickets.
 
-  2. As a rule, developers are totally not happy about the perspective of coping with incoming requests and answering them. The first line of support will still let through a lot of dilettante or badly formulated questions, and that will annoy on-duty API developers. There are several approaches to mitigate the problem:
-     * Try to find people with a customer-oriented mindset, who like this activity, and encourage them (including financial stimulus) to perform support functions; it might be someone on the team (and not necessarily a developer) or some active community member.
-     * The remaining load must be distributed among the developers equally and fairly, up to introducing the duty calendar.
+  2. As a rule, developers are totally not happy about the prospect of coping with incoming requests and answering them. The first line of support will still let through a lot of dilettante or poorly formulated questions, and that will annoy on-duty API developers. There are several approaches to mitigate this problem:
 
-And of course, analyzing the questions is a useful exercise to populate FAQs and improve the documentation and the first-line support scripts.
+     * Try to find individuals with a customer-oriented mindset who enjoy this activity, and encourage them (including financial stimulus) to perform support functions. This could be someone on the team (not necessarily a developer) or an active community member.
+
+     * Distribute the remaining workload among the developers equitably and fairly, up to introducing a duty calendar.
+
+And of course, analyzing the questions is a useful exercise for populating FAQs and improving documentation and first-line support scripts.
 
 #### External Platforms
 
-Sooner or later, you will find that customers ask their questions not only through the official channels, but also on numerous Internet-based forums, starting from those specifically created for this, like StackOverflow, and ending with social networks and personal blogs. It's up to you whether to spend time searching for such inquiries. We would rather recommend providing support through those platforms that have convenient tools for that (like subscribing to specific tags).
+Sooner or later, you will discover that customers ask their questions not only through official channels but also on various Internet-based forums, starting from those specifically created for this purpose, like StackOverflow, and ending with social networks and personal blogs. Whether you choose to invest time in searching for such inquiries is up to you. We would rather recommend providing support through platforms that offer convenient tools for supporting users, such as subscribing to specific tags.

src/en/clean-copy/07-Section VI. The API Product/11.md

@@ -1,52 +1,56 @@
-### [The Documentation][api-product-documentation]
+### [Documentation][api-product-documentation]
 
-Regretfully, many API providers pay miserable attention to the quality of documentation. Meanwhile, the documentation is the face of the product and the entry point to it. The problem becomes even worse if we acknowledge that it's almost impossible to write the help docs the developers will consider at least satisfactory.
+Regrettably, many API providers pay miserable attention to the quality of documentation. Meanwhile, documentation is the face of the product and the entry point to it. The problem becomes even worse when we acknowledge that it's almost impossible to write help articles that developers will find satisfactory.
 
-Before we start describing documentation types and formats, we should stress one important statement: developers interact with your help articles totally unlike you expect them to. Remember yourself working on the project: you make quite specific actions.
+Before we delve into describing documentation types and formats, we should emphasize one important point: developers interact with your help articles quite differently from what you might expect. Think about yourself working on a project; you take very specific actions:
 
-  1. First, you need to determine whether this service covers your needs in general (as quickly as possible);
-  2. If it does, you look for specific functionality to resolve your specific case.
+  1. First, you need to quickly determine whether this service meets your needs in general.
+  2. If it does, you then search for specific functionality to resolve your particular case.
 
-In fact, newcomers (i.e., those developers who are not familiar with the API) usually want just one thing: to assemble the code that solves their problem out of existing code samples and never return to this issue again. Sounds not exactly reassuringly, given the amount of work invested into the API and its documentation development, but that's what the reality looks like. Also, that's the root cause of developers' dissatisfaction with the docs: it's literally impossible to have articles covering exactly that problem the developer comes with being detailed exactly to the extent the developer knows the API concepts. In addition, non-newcomers (i.e., those developers who have already learned the basics concepts and are now trying to solve some advanced problems) do not need these “mixed examples” articles as they look for some deeper understanding.
+Newcomers (i.e., developers who are not familiar with the API) typically want just one thing: to assemble the code that solves their problem from existing code samples and never return to this issue again. Sounds not exactly reassuringly, given the amount of work invested in the API and its documentation development, but it is how the reality looks like. This is also the root cause of developers' dissatisfaction with the documentation: it is literally impossible to have articles that precisely cover the problem the developer is facing detailed exactly to the extent the developer understands the API concepts. Additionally, experienced users (i.e., developers who have already learned the basic concepts and are now trying to solve more advanced problems) do not need these “mixed examples” articles as they seek a deeper understanding.
 
 #### Introductory Notes
 
-Documentation frequently suffers from being excessively clerical; it's being written using formal terminology (which often requires reading the glossary before the actual docs) and is frequently unreasonably inflated. So instead of a two-word answer to a user's question, a couple of paragraphs is conceived — a practice we strongly disapprove of. The perfect documentation must be simple and laconic, and all the terms must be either explained in the text or given a reference to such an explanation. However, “simple” doesn't mean “illiterate”: remember, the documentation is the face of your product, so grammar errors and improper usage of terms are unacceptable.
+Documentation frequently suffers from excessive formality. It's often unnecessary inflated and written using terminology that requires consulting the glossary before reading the actual article. So instead of a concise answer to a user's question, a couple of paragraphs is conceived — a practice we strongly disapprove of. Ideal documentation must be simple and laconic, with all terms either explained in the text or referenced for clarification. However, “simple” doesn't mean “illiterate”: remember, documentation is the face of your product, so grammar errors and improper use of terms are unacceptable.
 
-Also, keep in mind that documentation will be used for searching as well, so every page should contain all the keywords required to be properly ranked by search engines. Unfortunately, this requirement contradicts the simple-and-laconic principle; this is the way.
+Also, keep in mind that documentation will be used for searching. Therefore, every page should contain all the necessary keywords to be properly ranked by search engines. Unfortunately, this requirement contradicts the principle of simplicity and conciseness. This is the way.
 
 #### Documentation Content Types
 
 ##### Specification / Reference
 
-Any documentation starts with a formal functional description. This content type is the most inconvenient to use, but you must provide it. A reference is the hygienic minimum of the API documentation. If you don't have a doc that describes all methods, parameters, options, variable types, and their allowed values, then it's not an API but amateur dramatics.
+Every documentation starts with a formal functional description. This content type is the most inconvenient to use, but it is essential. A reference is the hygienic minimum of the API documentation. If you don't have all methods, parameters, options, variable types, and their allowed values described, it's not an API but amateur dramatics.
 
-Today, a reference must be also a machine-readable specification, i.e., comply with some standard, for example, OpenAPI.
+Today, a reference must also be a machine-readable specification compatible with some standard, for example, OpenAPI.
 
-The specification must comprise not only formal descriptions but implicit agreements as well, such as the event generation order or unobvious side-effects of the API methods. Its important applied value is advisory consulting: developers will refer to it to clarify unobvious situations.
+The specification must comprise not only formal descriptions but also implicit agreements, such as the order of event generation or the less obvious side-effects of API methods. Its important applied value lies in advisory consulting: developers will refer to it to clarify unclear situations.
 
-**Importantly**, formal specification *is not documentation* per se. The documentation is *the words you write* in the descriptions of each field and method. Without them, the specification might be used just for checking whether your namings are fine enough for developers to guess their meaning.
+**Importantly**, a formal specification *is not documentation* per se. Documentation is *the words you write* in the descriptions of each field and method. Without these descriptions, the specification can only be used to check whether your naming is fine enough for developers to guess the meaning of signatures.
 
-Today, the method nomenclature descriptions are frequently additionally exposed as ready-to-use request collections or code fragments for Postman or analogous tools.
+Today, method nomenclature descriptions are often additionally presented as ready-to-use request collections or code fragments for Postman or similar tools.
 
 ##### Code Samples
 
-From the above-mentioned, it's obvious that code samples are a crucial tool to acquire and retain new API users. It's extremely important to choose examples that help newcomers to start working with the API. Improper example selection will greatly reduce the quality of your documentation. While assembling the set of code samples, it is important to follow the rules:
-  * Examples must cover actual API use cases: the better you guess the most frequent developers' needs, the more friendly and straightforward your API will look to them.
-  * Examples must be laconic and atomic: mixing a bunch of tricks in one code sample dramatically reduces its readability and applicability.
-  * Examples must be close to real-world app code. The author of this book once faced a situation when a synthetic code sample, totally meaningless in the real world, was mindlessly replicated by developers in abundance.
+From the above-mentioned, it is evident that code samples are a crucial tool for acquiring and retaining new API users. Well-chosen examples help newcomers start working with the API while improper example selection will greatly reduce the quality of your documentation. When assembling a set of code samples, it is important to follow these rules:
 
-Ideally, examples should be linked to all other kinds of documentation, e.g., the reference might contain code samples relevant to the entity being described.
+  * Examples must cover actual API use cases: the better you understand the most frequent developers' needs, the more friendly and straightforward your API will appear to them.
+
+  * Examples must be concise and atomic: mixing a bunch of tricks in one code sample dramatically reduces its readability and applicability.
+
+  * Examples must resemble real-world app code. The author of this book once faced a situation when a synthetic code sample, totally meaningless in the real world, was mindlessly replicated by developers in abundance.
+
+Ideally, examples should be linked to all other kinds of documentation. For example, the reference might contain code samples relevant to the entity being described.
 
 ##### Sandboxes
 
-Code samples will be much more useful to developers if they are “live,” i.e., provided as editable pieces of code that might be modified and executed. In the case of library APIs, the online sandbox featuring a selection of code samples will suffice, and existing online services like JSFiddle might be used. With other types of APIs, developing sandboxes might be much more complicated:
-  * If the API provides access to some data, then the sandbox must allow working with a real dataset, either a developer's own one (e.g., bound to their user profile) or some test data.
-  * If the API provides an interface, visual or programmatic, to some non-online environment, like UI libs for mobile devices do, then the sandbox itself must be an emulator or a simulator of that environment, in a form of an online service or a standalone app.
+Code samples will be much more useful to developers if they are “live,” i.e., provided as editable pieces of code that could be modified and executed. In the case of library APIs, an online sandbox featuring a selection of code samples will suffice, and existing online services like JSFiddle might be used. With other types of APIs, developing sandboxes could be much more complicated:
 
-##### Tutorial
+  * If the API provides access to some data, then the sandbox must allow working with a real dataset, either a developer's own (e.g., bound to their user profile) or some test data.
+  * If the API provides an interface, visual or programmatic, to some non-online environment, like UI libs for mobile devices do, then the sandbox itself must be an emulator or a simulator of that environment, in the form of an online service or a standalone app.
 
-A tutorial is a specifically written human-readable text describing some concepts of working with the API. A tutorial is something in-between a reference and examples. It implies some learning, more thorough than copy-pasting code samples, but requires less time investment than reading the whole reference.
+##### Tutorials
+
+A tutorial is a specifically written human-readable text describing concepts of working with the API. A tutorial is something in-between a reference and examples. It implies some learning, more thorough than copy-pasting code samples, but requires less time investment than reading the whole reference.
 
 A tutorial is a sort of “book” that you write to explain to the reader how to work with your API. So, a proper tutorial must follow book-writing patterns, i.e., explain the concepts coherently and consecutively chapter after chapter. Also, a tutorial must provide:
   * General knowledge of the subject area; for example, a tutorial for cartographical APIs must explain trivia regarding geographical coordinates and working with them
@@ -56,14 +60,14 @@ A tutorial is a sort of “book” that you write to explain to the reader how t
 
 Usually, a tutorial comprises a common section (basic terms and concepts, notation keys) and a set of sections regarding each functional domain exposed via the API. Frequently, tutorials contain a “Quick Start” (“Hello, world!”) section: the smallest possible code sample that would allow developers to build a small app atop the API. “Quick Starts” aim to cover two needs:
   * To provide a default entry-point, the easiest to understand and the most useful text for those who heard about your API for the first time
-  * To engage developers, to make them touch the service by a mean of a real-world example.
+  * To engage developers, to make them interact with the service by means of a real-world example.
 
-Also, “Quick starts” are a good indicator of how exactly well did you do your homework of identifying the most important use cases and providing helper methods. If your Quick Start comprises more than ten lines of code, you have definitely done something wrong.
+Also, “Quick starts” are a good indicator of how well you have done your homework of identifying the most important use cases and providing helper methods. If your Quick Start comprises more than ten lines of code, you have definitely done something wrong.
 
 ##### Frequently Asked Questions and Knowledge Bases
 
-After you publish the API and start supporting users (see the previous chapter) you will also accumulate some knowledge of what questions are asked most frequently. If you can't easily integrate answers into the documentation, it's useful to compile a specific “Frequently Asked Questions” (aka FAQ) article. A FAQ article must meet the following criteria:
-  * Address the real questions (you might frequently find FAQs that were reflecting not users' needs, but the API owner's desire to repeat some important information once more; it's useless, or worse — annoying; perfect examples of this anti-pattern realization might be found on any bank or air company website)
+After you publish the API and start supporting users (see the previous chapter) you will also accumulate some knowledge about what questions are asked most frequently. If you can't easily integrate answers into the documentation, it's useful to compile a specific “Frequently Asked Questions” (aka FAQ) article. A FAQ article must meet the following criteria:
+  * Address the real questions (you might frequently find FAQs that were reflecting not users' needs, but the API owner's desire to repeat some important information once more; it's useless, or worse — annoying; perfect examples of this anti-pattern realization might be found on any bank or airline company website)
   * Both questions and answers must be formulated clearly and succinctly. It's acceptable (and even desirable) to provide links to corresponding reference and tutorial articles, but the answer itself can't be longer than a couple of paragraphs.
 
 Also, FAQs are a convenient place to explicitly highlight the advantages of the API. In a question-answer form, you might demonstrably show how your API solves complex problems easily and handsomely. (Or at least, *solves them*, unlike the competitors' products.)
@@ -72,7 +76,7 @@ If technical support conversations are public, it makes sense to store all the q
 
 ##### Offline Documentation
 
-Though we live in the online world, an offline version of the documentation (in a form of a generated doc file) still might be useful — first of all, as a snapshot of the API specification valid for a specific date.
+Though we live in the online world, an offline version of the documentation (in the form of a generated file) still might be useful — first of all, as a snapshot of the API specification valid for a specific date.
 
 #### Content Duplication Problems
 
@@ -87,7 +91,7 @@ The problem becomes worse if you're supporting not only different API versions b
 
 In this case, you need to choose one of the following strategies:
   * If the documentation topic content is totally identical for every platform, i.e., only the code syntax differs, you will need to develop generalized documentation: each article provides code samples (and maybe some additional notes) for every supported platform on a single page.
-  * On the contrary, if the content differs significantly, as is in the iOS/Android case, we might suggest splitting the documentation sites (up to having separate domains for each platform): the good news is that developers almost always need one specific version, and they don't care about other platforms.
+  * On the contrary, if the content differs significantly, as is the case with iOS / Android, we might suggest splitting the documentation sites (up to having separate domains for each platform): the good news is that developers almost always need one specific version, and they don't care about other platforms.
 
 #### The Documentation Quality
 

src/en/clean-copy/07-Section VI. The API Product/12.md

@@ -1,34 +1,37 @@
 ### [Testing Environments][api-product-testing]
 
-If the operations executed via the API imply consequences for end users or partners (cost money, in particular) you must provide a test version of the API. In this testing API, real-world actions either don't happen at all (for instance, orders are created but nobody serves them) or are simulated by cheaper means (let's say, instead of sending an SMS to a user, an email is sent to the developer's mailbox).
+If the operations executed via the API have consequences for end users or partners (especially those that involve costs) you must provide a test version of the API. In this testing API, real-world actions either don't occur at all (for instance, orders are created but nobody serves them) or are simulated using cost-effective methods (for example, sending an email to the developer's mailbox instead of an SMS to the user).
 
-However, in many cases having a test version is not enough — like in our coffee-machine API example. If an order is created but not served, partners are not able to test the functionality of delivering the order or requesting a refund. To run the full cycle of testing, developers need the capability of pushing the order through stages, as this would happen in reality.
+However, in many cases having a test version is not enough, as in our coffee-machine API example. If an order is created but not fulfilled, partners cannot test the functionality of delivering the order or requesting a refund. To conduct a complete testing cycle, developers need the capability of pushing the order through stages, just as it would happen in reality.
 
-A direct solution to this problem is providing test versions for a full set of APIs and administrative interfaces. It means that developers will be able to run a second application in parallel — the one you're giving to coffee shops so they might get and serve orders (and if there is a delivery functionality, the third app as well: the courier's one) — and make all these actions that coffee shop staff normally does. Obviously, that's not an ideal solution, because of several reasons:
-  * Developers of end user applications will need to additionally learn how coffee shop and courier apps work, which has nothing to do with the task they're solving.
-  * You will need to invent and implement some matching algorithm: an order made through a test application must be assigned to a specific virtual courier; this actually means creating an isolated virtual “sandbox” (meaning — a full set of services) for each specific partner.
-  * Executing a full “happy path” of an order will take minutes, maybe tens of minutes, and will require making a multitude of actions in several different interfaces.
+A direct solution to this problem is providing test versions for a full set of APIs and administrative interfaces. This means that developers will be able to run a second application in parallel — the one you provide to coffee shops for receiving and serving orders (and if there is a delivery functionality, a third app, for couriers) — and perform all the actions that coffee shop staff normally does. Obviously, this is not an ideal solution for several reasons:
 
-There are two main approaches to tackling these problems.
+  * Developers of end user applications will need to additionally learn how coffee shop and courier apps work, which is unrelated to the task they're solving.
+
+  * You will need to invent and implement some matching algorithm: an order made through a test application must be assigned to a specific virtual courier. This actually means creating an isolated virtual “sandbox” (meaning — a full set of services) for each specific partner.
+
+  * Executing a full “happy path” of an order will take minutes, maybe tens of minutes, and will require performing a multitude of actions in several different interfaces.
+
+There are two main approaches to addressing these problems.
 
 ##### The Testing Environment API
 
-The first option is providing a meta-API to the testing environment itself. Instead of running the coffee-shop app in a separate simulator, developers are provided with helper methods (like `simulateOrderPreparation`) or some visual interface that allows controlling the order execution pipeline with minimum effort.
+The first option is to provide a meta-API for the testing environment itself. Instead of running the coffee-shop app in a separate simulator, developers are given helper methods (like `simulateOrderPreparation`) or a visual interface that allows them to control the order execution pipeline with minimal effort.
 
-Ideally, you should provide helper methods for any actions that are conducted by people in the production environment. It makes sense to ship this meta-API complete with ready-to-use scripts or request collections that show the correct API call orders for standard scenarios. 
+Ideally, you should equip this meta-API with helper methods for any actions that are conducted by people in the production environment. It makes sense to provide ready-to-use scripts or request collections that demonstrate the correct API call orders for standard scenarios. 
 
-The disadvantage of this approach is that client developers still need to know how the “flip side” of the system works, though in simplified terms.
+The disadvantage of this approach is that client developers still need to understand how the “flip side” of the system works, albeit in simplified terms.
 
 ##### The Simulator of Pre-Defined Scenarios
 
-The alternative to providing the testing environment API is simulating the working scenarios. In this case, the testing environment takes control over “underwater” parts of the system and “plays out” all external agents' actions. In our coffee example, that means that, after the order is submitted, the system will simulate all the preparation steps and then the delivery of the beverage to the customer.
+The alternative to providing the testing environment API is to simulate the working scenarios. In this case, the testing environment takes control over the “underwater” parts of the system and “plays out” all external agents' actions. In our coffee example, this means that after the order is submitted, the system will simulate all the preparation steps and then the delivery of the beverage to the customer.
 
-The advantage of this approach is that it demonstrates vividly how the system works according to the API vendor design plans, e.g., in which sequence the events are generated, and which stages the order passes through. It also reduces the chance of making mistakes in testing scripts, as the API vendor guarantees the actions will be executed in the correct order with the right parameters.
+The advantage of this approach is that it vividly demonstrates how the system works according to the API vendor's design plans. For example, it shows the sequence in which events are generated and the stages the order passes through. It also reduces the chance of making mistakes in testing scripts since the API vendor guarantees that the actions will be executed in the correct order with the right parameters.
 
-The main disadvantage is the necessity to create a separate scenario for each unhappy path (effectively, for every possible error), and give developers the capability of denoting which scenario they want to run. (For example, like that: if there is a pre-agreed comment to the order, the system will simulate a specific error, and developers will be able to write and debug the code that deals with the error.)
+The main disadvantage is the necessity to create a separate scenario for each unhappy path (effectively, for every possible error) and give developers the capability to specify which scenario they want to run. (For example, like this: if there is a pre-agreed comment in the order, the system will simulate a specific error, and developers will be able to write and debug the code that deals with the error.)
 
 #### The Automation of Testing
 
-Your final goal in implementing testing APIs, regardless of which option you choose, is allowing partners to automate the QA process for their products. The testing environment should be developed with this purpose in mind; for example, if an end user might be brought to a 3-D Secure page to pay for the order, the testing environment API must provide some way of simulating the successful (or not) passing of this step. Also, in both variants, it's possible (and desirable) to allow running the scenarios in a fast-forward manner that will allow making auto-testing much faster than manual testing.
+Your final goal in implementing testing APIs, regardless of which option you choose, is to allow partners to automate the QA process for their products. The testing environment should be developed with this purpose in mind. For example, if an end user might be directed to a 3-D Secure page to pay for the order, the testing environment API must provide a way to simulate the successful (or unsuccessful) completion of this step. Also, in both variants, it's possible (and desirable) to allow running the scenarios in a fast-forward manner to make automated testing much faster than manual testing.
 
-Of course, not every partner will be able to employ this possibility (which also means that a “manual” way of testing usage scenarios must always be supported alongside the programmatical one) simply because not every business might afford to hire a QA automation engineer. Nevertheless, the ability to write such auto-tests is your API's huge competitive advantage from a technically advanced partner's point of view. 
+Of course, not every partner will be able to take advantage of this possibility (which also means that a “manual” way of testing usage scenarios must always be supported alongside the programmatic one) simply because not every business could afford to hire a QA automation engineer. Nevertheless, the ability to write such automated tests is a significant competitive advantage for your API from a technically advanced partner's point of view. 

src/en/clean-copy/07-Section VI. The API Product/13.md

@@ -1,25 +1,25 @@
 ### [Managing Expectations][api-product-expectations]
 
-Finally, the last aspect we would like to shed the light on is managing partners' expectations regarding the further development of the API. If we talk about consumer qualities, APIs differ little from other B2B software products: in both cases, you need to form some understanding of SLA conditions, available features, interface responsiveness and other characteristics that are important for clients. Still, APIs have their specificities
+Finally, the last aspect we would like to shed light on is managing partners' expectations regarding the further development of the API. When we talk about consumer qualities, APIs differ little from other B2B software products: in both cases, you need to form an understanding of SLA conditions, available features, interface responsiveness and other characteristics that are important for clients. Still, APIs have their specificities.
 
 #### Versioning and Application Lifecycle
 
-Ideally, the API once published should live eternally; but as we all are reasonable people, we do understand it's impossible in the real life. Even if we continue supporting older versions, they will still become outdated eventually, and partners will need to rewrite the code to use newer functionality.
+Ideally, the API once published should live eternally; but as we are all reasonable people, we do understand it's impossible in the real world. Even if we continue supporting older versions, they will still become outdated eventually, and partners will need to rewrite the code to use newer functionality.
 
-The author of this book formulates the rule of issuing new major API versions like this: the period of time after which partners will need to rewrite the code should coincide with the application lifespan in the subject area (see “[The Backward Compatibility Problem Statement](#back-compat-statement)” chapter). Apart from updating *major* versions, sooner or later you will face issues with accessing some outdated *minor* versions as well. As we mentioned in the “[On the Waterline of the Iceberg](#back-compat-iceberg-waterline)” chapter, even fixing bugs might eventually lead to breaking some integrations, and that naturally leads us to the necessity of keeping older *minor* versions of the API until the partner resolves the problem.
+The author of this book formulates the rule of issuing new major API versions like this: the period of time after which partners will need to rewrite the code should coincide with applications' lifespan in the subject area (see “[The Backward Compatibility Problem Statement](#back-compat-statement)” chapter). Apart from updating *major* versions, sooner or later you will face issues with accessing some outdated *minor* versions as well. As we mentioned in the “[On the Waterline of the Iceberg](#back-compat-iceberg-waterline)” chapter, even fixing bugs might eventually lead to breaking some integrations, and that naturally leads us to the necessity of keeping older *minor* versions of the API until the partner resolves the problem.
 
-In this aspect, integrating with large companies that have a dedicated software engineering department differs dramatically from providing a solution to individual amateur programmers: on one hand, the former are much more likely to find undocumented features and unfixed bugs in your code; on the other hand, because of the internal bureaucracy, fixing the related issues might easily take months, save not years. The common recommendation there is to maintain old minor API versions for a period of time long enough for the most dilatory partner to switch no the newest version.
+In this aspect, integrating with large companies that have a dedicated software engineering department differs dramatically from providing a solution to individual amateur programmers. On one hand, the former are much more likely to find undocumented features and unfixed bugs in your code; on the other hand, because of the internal bureaucracy, fixing the related issues might easily take months, if not years. The common recommendation there is to maintain old minor API versions for a period of time long enough for the most dilatory partner to switch to the newest version.
 
 #### Supporting Platforms
 
-Another aspect crucial to interacting with large integrators is supporting a zoo of platforms (browsers, programming languages, protocols, operating systems) and their versions. As usual, big companies have their own policies on which platforms they support, and these policies might sometimes contradict common sense. (Let's say, it's rather a time to abandon TLS 1.2, but many integrators continue working through this protocol, or even the earlier ones.)
+Another aspect crucial to interacting with large integrators is supporting a zoo of platforms (browsers, programming languages, protocols, operating systems) and their versions. As usual, big companies have their own policies on which platforms they support, and these policies might sometimes contradict common sense. (Let's say, it's rather time to abandon TLS 1.2, but many integrators continue working through this protocol, or even the earlier ones.)
 
-Formally speaking, ceasing support of a platform *is* a backward-incompatible change, and might lead to breaking some integration for some end users. So it's highly important to have clearly formulated policies regarding which platforms are supported based on which criteria. In the case of mass public APIs, that's usually simple (like, API vendor promises to support platforms that have more than N% penetration, or, even easier, just last M versions of a platform); in the case of commercial APIs, it's always a bargain based on the estimations, how much will non-supporting a specific platform would cost to a company. And of course, the outcome of the bargain must be stated in the contracts — what exactly you're promising to support during which period of time.
+Formally speaking, ceasing support of a platform *is* a backward-incompatible change, and it might lead to breaking some integration for some end users. So it's highly important to have clearly formulated policies regarding which platforms are supported based on which criteria. In the case of mass public APIs, that's usually simple (like, the API vendor promises to support platforms that have more than N% penetration, or, even easier, just the last M versions of a platform); in the case of commercial APIs, it's always a bargain based on estimations, how much not supporting a specific platform would cost a company. And of course, the outcome of the bargain must be stated in the contracts — what exactly you're promising to support during which period of time.
 
 #### Moving Forward
 
-Finally, apart from those specific issues, your customers must be caring about more general questions: could they trust you? Could they rely on your API evolving, absorbing modern trends, or will they eventually find the integration with your API on the scrapyard of history? Let's be honest: given all the uncertainties of the API product vision, we are very much interested in the answers as well. Even the Roman viaduct, though remaining backward-compatible for two thousand years, has been a very archaic and non-reliable way of solving customers' problems for quite a long time.
+Finally, apart from those specific issues, your customers must be caring about more general questions: could they trust you? Could they rely on your API evolving, absorbing modern trends, or will they eventually find the integration with your API in the scrapyard of history? Let's be honest: given all the uncertainties of the API product vision, we are very much interested in the answers as well. Even the Roman viaduct, though remaining backward-compatible for two thousand years, has been a very archaic and non-reliable way of solving customers' problems for quite a long time.
 
-You might work with these customer expectations by publishing roadmaps. It's quite common that many companies avoid publicly announcing their concrete plans (for a reason, of course). Nevertheless, in the case of APIs, we strongly recommend providing the roadmaps, even if they are tentative and lack precise dates — *especially* if we talk about deprecating some functionality. Announcing these promises (given the company keeps them, of course) is a very important competitive advantage to every kind of consumer.
+You might work with these customer expectations by publishing roadmaps. It's quite common that many companies avoid publicly announcing their concrete plans (for a reason, of course). Nevertheless, in the case of APIs, we strongly recommend providing roadmaps, even if they are tentative and lack precise dates — *especially* if we talk about deprecating some functionality. Announcing these promises (given the company keeps them, of course) is a very important competitive advantage for every kind of consumer.
 
-With this, we would like to conclude this book. We hope that the principles and the concepts we have outlined will help you in creating APIs that fit all the developers, businesses, and end users' needs, and in expanding them (while maintaining the backward compatibility) for the next two thousand years or so.
+With this, we would like to conclude this book. We hope that the principles and the concepts we have outlined will help you in creating APIs that fit all the developers, businesses, and end users' needs and in expanding them (while maintaining backward compatibility) for the next two thousand years or so.