style fix

src/en/clean-copy/01-Introduction/06.md

@@ -1,6 +1,6 @@
 ### Terms and Notation Keys
 
-Software development is characterized, among other things, by the existence of many different engineering paradigms, whose adepts sometimes are quite aggressive towards other paradigms' adepts. While writing this book, we are deliberately avoiding using terms like “method”, “object”, “function”, and so on, using the neutral term “entity” instead. “Entity” means some atomic functionality unit, like class, method, object, monad, prototype (underline what you think is right).
+Software development is characterized, among other things, by the existence of many different engineering paradigms, whose adepts sometimes are quite aggressive towards other paradigms' adepts. While writing this book, we are deliberately avoiding using terms like “method,” “object,” “function,” and so on, using the neutral term “entity” instead. “Entity” means some atomic functionality unit, like class, method, object, monad, prototype (underline what you think is right).
 
 As for an entity's components, we regretfully failed to find a proper term, so we will use the words “fields” and “methods.”
 

src/en/clean-copy/02-Section I. The API Design/03.md

@@ -112,7 +112,7 @@ Abstraction levels separation should go in three directions:
 
   1. From user scenarios to their internal representation: high-level entities and their method nomenclatures must directly reflect the API usage scenarios; low-level entities reflect the decomposition of the scenarios into smaller parts.
 
-  2. From user to “raw” data subject field terms — in our case from high-level terms like “order”, “recipe”, “café” to low-level terms like “beverage temperature”, “coffee machine geographical coordinates”, etc.
+  2. From user to “raw” data subject field terms — in our case from high-level terms like “order,” “recipe,” “café” to low-level terms like “beverage temperature,” “coffee machine geographical coordinates,” etc.
 
   3. Finally, from data structures suitable for end users to “raw” data structures — in our case, from “lungo recipe” and “"Chamomile" café chain” to the raw byte data stream from “Good Morning” coffee machine sensors.
 
@@ -149,7 +149,7 @@ An experienced developer in this case must ask: what options do exist? how shoul
 
 In our example let's assume that we have studied coffee machines' API specs, and learned that two device types exist:
   * coffee machines capable of executing programs coded in the firmware; the only customizable options are some beverage parameters, like desired volume, a syrup flavor, and a kind of milk;
-  * coffee machines with built-in functions, like “grind specified coffee volume”, “shed the specified amount of water”, etc.; such coffee machines lack “preparation programs,” but provide access to commands and sensors.
+  * coffee machines with built-in functions, like “grind specified coffee volume,” “shed the specified amount of water,” etc.; such coffee machines lack “preparation programs,” but provide access to commands and sensors.
 
 To be more specific, let's assume those two kinds of coffee machines provide the following physical API.
 

src/en/clean-copy/02-Section I. The API Design/05.md

@@ -89,7 +89,7 @@ It is also worth saying that in some areas the situation with standards is so sp
 
 ##### Entities must have concrete names
 
-Avoid single amoeba-like words, such as “get”, “apply”, “make”, etc.
+Avoid single amoeba-like words, such as “get,” “apply,” “make,” etc.
 
 **Bad**: `user.get()` — hard to guess what is actually returned.
 

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

@@ -37,7 +37,7 @@ The first problem is obvious to those who read [chapter 11](#chapter-11-paragrap
 ]
 ```
 
-And here the first big question arises: what should we do with the `default_volume` field? From one side, that's an objective quality measured in standardized units, and it's being passed to the program execution engine. On the other side, in countries like the United States, we had to specify beverage volume not like “300 ml”, but “10 fl oz.” We may propose two solutions:
+And here the first big question arises: what should we do with the `default_volume` field? From one side, that's an objective quality measured in standardized units, and it's being passed to the program execution engine. On the other side, in countries like the United States, we had to specify beverage volume not like “300 ml,” but “10 fl oz.” We may propose two solutions:
 
   * either the partner provides the corresponding number only, and we will make readable descriptions on our own behalf,
   * or the partner provides both the number and all of its localized representations.
@@ -46,7 +46,7 @@ The flaw in the first option is that a partner might be willing to use the servi
 
 The localization flaws are not the only problem with this API. We should ask ourselves a question — *why* do we really need these `name` and `description`? They are simply non-machine-readable strings with no specific semantics. At first glance, we need them to return them back in the `/v1/search` method response, but that's not a proper answer: why do we really return these strings from `search`?
 
-The correct answer lies a way beyond this specific interface. We need them *because some representation exists*. There is a UI for choosing beverage type. Probably the `name` and `description` fields are simply two designations of the beverage for a user to read, a short one (to be displayed on the search results page) and a long one (to be displayed in the extended product specification block). It actually means that we are setting the requirements to the API based on some very specific design. But *what if* a partner is making their own UI for their own app? Not only they might not actually need two descriptions, but we are also *deceiving* them. The `name` is not “just a name” actually, it implies some restrictions: it has recommended length which is optimal to some specific UI, and it must look consistently on the search results page. Indeed, “our best quality™ coffee” or “Invigorating Morning Freshness®” designation would look very weird in between “Cappuccino”, “Lungo”, and “Latte.”
+The correct answer lies a way beyond this specific interface. We need them *because some representation exists*. There is a UI for choosing beverage type. Probably the `name` and `description` fields are simply two designations of the beverage for a user to read, a short one (to be displayed on the search results page) and a long one (to be displayed in the extended product specification block). It actually means that we are setting the requirements to the API based on some very specific design. But *what if* a partner is making their own UI for their own app? Not only they might not actually need two descriptions, but we are also *deceiving* them. The `name` is not “just a name” actually, it implies some restrictions: it has recommended length which is optimal to some specific UI, and it must look consistently on the search results page. Indeed, “our best quality™ coffee” or “Invigorating Morning Freshness®” designation would look very weird in between “Cappuccino,” “Lungo,” and “Latte.”
 
 There is also another side to this story. As UIs (both ours and partners) tend to evolve, new visual elements will be eventually introduced. For example, a picture of a beverage, its energy value, allergen information, etc. `product_properties` will become a scrapyard for tons of optional fields, and learning how setting what field results in what effects in the UI will be an interesting quest, full of probes and mistakes.