clarifications & style fixes

src/en/clean-copy/03-Section II. The Backwards Compatibility/03.md

@@ -12,7 +12,7 @@ Let us make the next logical step there and suppose that partners will wish to d
   * registering new API types in the system;
   * providing the list of the coffee machines and their API types;
 
-For example, we might provide the following methods.
+For example, we might provide a second API family (the partner-bound one) with the following methods:
 
 ```
 // 1. Register a new API type
@@ -52,7 +52,7 @@ It may look like there are no such things in our API since it's quite simple and
 
 We have written down this list having one purpose in mind: we need to understand, how exactly will we make these implicit arrangements explicit if we need that. For example, if different coffee machines provide different functionality — let's say, some of them are capable of brewing fixed beverage volumes only — what would change in our API?
 
-The universal approach to making such amendments is: to consider the existing interface as a reduction of some more general one like if some parameters were set to defaults and therefore omitted. So making a change is always a three-step process.
+The universal approach to making such amendments is: to consider the existing interface as a reduction of some more general one like if some parameters were set to defaults and therefore omitted. So making a change is always a three-step process:
 
   1. Explicitly define the programmatical contract *as it works right now*.
   2. Extend the functionality: add a new method allowing for tackling those restrictions set in the previous paragraph.
@@ -87,9 +87,9 @@ Usually, just adding a new optional parameter to the existing interface is enoug
 
 #### Limits of Applicability
 
-Though this exercise looks very simple and universal, its consistent usage is possible only if the hierarchy of entities is well designed from the very beginning and, which is more important, the vector of the further API expansion is clear. Imagine that after some time passed, the options list got new items; let's say, adding syrup or a second espresso shot. We are totally capable of expanding the list — but not the defaults. So the “default” `PUT /coffee-machines` interface will eventually become totally useless because the default set of three options will not only be any longer of use but will also look ridiculously: why these three options, what are the selection criteria? In fact, the defaults and the method list will be reflecting the historical stages of our API development, and that's totally not what you'd expect from the helpers and defaults nomenclature.
+Though this exercise looks very simple and universal, its consistent usage is possible only if the hierarchy of entities is well-designed from the very beginning and, which is more important, the vector of the further API expansion is clear. Imagine that after some time passed, the options list got new items; let's say, adding syrup or a second espresso shot. We are totally capable of expanding the list — but not the defaults. So the “default” `PUT /coffee-machines` interface will eventually become totally useless because the default set of three options will not only be any longer of use but will also look ridiculously: why these three options, what are the selection criteria? In fact, the defaults and the method list will be reflecting the historical stages of our API development, and that's totally not what you'd expect from the helpers and defaults nomenclature.
 
-Alas, this dilemma can't be easily resolved. From one side, we want developers to write neat and laconic code, so we must provide useful helpers and defaults. On the other side, we can't know in advance which sets of options will be the most frequent after several years of the API expansion.
+Alas, this dilemma can't be easily resolved. On one hand, we want developers to write neat and laconic code, so we must provide useful helpers and defaults. On the other hand, we can't know in advance which sets of options will be the most useful after several years of the API expansion.
 
 **NB**. We might mask this problem in the following manner: one day gather all these oddities and re-define all the defaults with one single parameter. For example, introduce a special method like `POST /use-defaults {"version": "v2"}` which would overwrite all the defaults with more suitable values. That will ease the learning curve, but your documentation will become even worse after that.
 

src/ru/clean-copy/03-Раздел II. Обратная совместимость/03.md

@@ -12,7 +12,7 @@
   * регистрации в системе новых типов API;
   * загрузки списка кофемашин партнёра с указанием типа API.
 
-Например, можно предоставить вот такие методы.
+Например, можно предоставить второе семейство API (специально для партнёров), содержащее вот такие методы.
 
 ```
 // 1. Зарегистрировать новый тип API