From 4040e8866510879a6b98296e81e4eca31931ab72 Mon Sep 17 00:00:00 2001
From: Kevin Harper <keharper@adobe.com>
Date: Mon, 15 Jul 2019 16:01:29 -0500
Subject: [PATCH 1/2] fixed broken glossary links

---
 .../v2.2/extension-dev-guide/api-concepts.md  | 25 +++---
 .../service-contracts/design-patterns.md      | 81 ++++++++++---------
 .../service-contracts/service-contracts.md    | 31 ++++---
 3 files changed, 71 insertions(+), 66 deletions(-)

diff --git a/guides/v2.2/extension-dev-guide/api-concepts.md b/guides/v2.2/extension-dev-guide/api-concepts.md
index 69777cbad02..408ef28a840 100644
--- a/guides/v2.2/extension-dev-guide/api-concepts.md
+++ b/guides/v2.2/extension-dev-guide/api-concepts.md
@@ -8,24 +8,25 @@ menu_order: 3
 
 ## What is a public interface? {#public-interface}
 
-<p>A <i>public interface</i> is a set of code that third-party developers can call, implement, or build as a [plug-in](https://glossary.magento.com/plug-in). Magento guarantees that this code will not change in subsequent releases without a major version change.</p>
-<p>Public interfaces for a [module](https://glossary.magento.com/module) are marked with <code>@api</code> annotation.</p>
+A _public interface_ is a set of code that third-party developers can call, implement, or build as a [plug-in](https://glossary.magento.com/plug-in). Magento guarantees that this code will not change in subsequent releases without a major version change.
+
+Public interfaces for a [module](https://glossary.magento.com/module) are marked with `@api` annotation.
 
 {: .bs-callout-info }
 Third-party developers should use only these interfaces, that is, interfaces with the `@api` annotation. You can use other interfaces but those may be modified or removed in subsequent Magento releases. For more information, see [Backward compatibility]({{ page.baseurl }}/contributor-guide/backward-compatible-development/).
 
 ## What is an API? {#api-definition}
 
-<p>An application programming interface (API) is a set of interfaces and their implementations that a module provides to other modules.</p>
+An application programming interface (API) is a set of interfaces and their implementations that a module provides to other modules.
 
 ### API types {#api-types}
 
-<p>The following items are considered types of APIs:</p>
-<ul>
-   <li>Directory structure</li>
-   <li>Configuration files structure</li>
-   <li>Events</li>
-   <li>Client API</li>
-   <li>Provider [API](https://glossary.magento.com/api) (SPI)</li>
-</ul>
-<p>Directory structure and configuration file structure are types of APIs because [extension](https://glossary.magento.com/extension) developers use them. Developers write configurations, and place their [static files](https://glossary.magento.com/static-files) in specified folders; so if the configuration file structure or directory structure changes in subsequent releases, modules and extensions may break.</p>
+The following items are considered types of APIs:
+
+- Directory structure
+- Configuration files structure
+- Events
+- Client API
+- Provider [API](https://glossary.magento.com/api) (SPI)
+
+Directory structure and configuration file structure are types of APIs because [extension](https://glossary.magento.com/extension) developers use them. Developers write configurations, and place their [static files](https://glossary.magento.com/static-files) in specified folders; so if the configuration file structure or directory structure changes in subsequent releases, modules and extensions may break.
diff --git a/guides/v2.2/extension-dev-guide/service-contracts/design-patterns.md b/guides/v2.2/extension-dev-guide/service-contracts/design-patterns.md
index e592ff6b117..3af8925835f 100644
--- a/guides/v2.2/extension-dev-guide/service-contracts/design-patterns.md
+++ b/guides/v2.2/extension-dev-guide/service-contracts/design-patterns.md
@@ -6,20 +6,22 @@ menu_title: Service contract design patterns
 menu_order: 4
 ---
 
-<p>In the programming community, a <i>design pattern</i> is a recommended way of writing code that includes when to use, or not use, the pattern. Think of a [design pattern](https://glossary.magento.com/design-pattern) as a best practice with conditions.</p>
-<p>Design patterns for service contracts tell you which types of interfaces to define, and how and where to define and implement those  interfaces.</p>
+In the programming community, a _design pattern_ is a recommended way of writing code that includes when to use, or not use, the pattern. Think of a [design pattern](https://glossary.magento.com/design-pattern) as a best practice with conditions.
+
+Design patterns for service contracts tell you which types of interfaces to define, and how and where to define and implement those interfaces.
 
 {: .bs-callout-info }
 Service contract data interfaces are now mutable.
 
 ## Interface types and locations {#top-level-msc}
 
-<p>A [service contract](https://glossary.magento.com/service-contract) must define data interfaces, which preserve data integrity, and service interfaces, which hide business logic from service requestors.</p>
-<p>Data interfaces define functions that return information about data entities, return search results, and set validation rules and return validation results. You must define the data interfaces for a service contract in the <b>Api/Data</b> subdirectory for a [module](https://glossary.magento.com/module).</p>
-<p>
-   Service interfaces include management, repository, and [metadata](https://glossary.magento.com/metadata) interfaces.
-   You must define the service interfaces for a service contract in the <b>Api</b> subdirectory for a module.<!--  You can substitute another implementation in this directory. -->
-</p>
+A [service contract](https://glossary.magento.com/service-contract) must define data interfaces, which preserve data integrity, and service interfaces, which hide business logic from service requestors.
+
+Data interfaces define functions that return information about data entities, return search results, and set validation rules and return validation results. You must define the data interfaces for a service contract in the `Api/Data` subdirectory for a [module](https://glossary.magento.com/module).
+
+Service interfaces include management, repository, and [metadata](https://glossary.magento.com/metadata) interfaces.
+You must define the service interfaces for a service contract in the `Api` subdirectory for a module.<!--  You can substitute another implementation in this directory. -->
+
 <!--
    <p>For example, the interfaces in the <b>Magento\Customer\Api</b> [namespace](https://glossary.magento.com/namespace) define agreements, or a contract, between clients and implementations of services for the Magento Customer module.
                   </p>
@@ -27,38 +29,42 @@ Service contract data interfaces are now mutable.
 
 ## Data interfaces {#data-interfaces}
 
-<p>Define data interfaces in the <b>Api/Data</b> subdirectory for a module.</p>
-<p>For example, the data interfaces for the Customer module are in the <b>/app/code/Magento/Customer/Api/Data</b> subdirectory.</p>
+Define data interfaces in the `Api/Data` subdirectory for a module.
+
+For example, the data interfaces for the Customer module are in the `/app/code/Magento/Customer/Api/Data` subdirectory.
 
 ### Data search results interfaces {#search-results-interfaces}
 
-<p>When you pass search criteria to a <code>getList()</code> call, a search results interface is returned with the search results.</p>
-<p>You must define one interface for each data [entity](https://glossary.magento.com/entity) for type hinting purposes. That is, the <code>getItems()</code> function in the
-   <code>CustomerSearchResultsInterface</code> returns an array of <code>CustomerInterface</code> data entities.
-   In <code>GroupSearchResultsInterface</code>, the <code>getItems()</code> function returns an array of <code>GroupInterface</code> data entities.
-</p>
+When you pass search criteria to a `getList()` call, a search results interface is returned with the search results.
+
+You must define one interface for each data [entity](https://glossary.magento.com/entity) for type hinting purposes. That is, the `getItems()` function in the
+`CustomerSearchResultsInterface` returns an array of `CustomerInterface` data entities.
+In `GroupSearchResultsInterface`, the `getItems()` function returns an array of `GroupInterface` data entities.
 
 ## Service interfaces {#service-interfaces}
 
-<p>Service interfaces include several interface subtypes:</p>
-<ul>
-   <li>Repository interfaces</li>
-   <li>Management interfaces</li>
-   <li>Metadata interfaces</li>
-</ul>
-<p>For file names and coding standards, follow the defined <a href="{{ page.baseurl }}/coding-standards/code-standard-php.html">PHP coding standards</a>.</p>
-<p>Place service interfaces in the top-level <b>Api</b> directory for a module.</p>
+Service interfaces include several interface subtypes:
+
+- Repository interfaces
+- Management interfaces
+- Metadata interfaces
+
+For file names and coding standards, follow the defined [PHP coding standards]("{{ page.baseurl }}/coding-standards/code-standard-php.html).
+
+Place service interfaces in the top-level `Api` directory for a module.
 
 ### Repository interfaces {#repository-interfaces}
 
-<p>Repository interfaces provide access to persistent data entities.</p>
-<p>For example, persistent data entities for the Customer module include Customer, Address, and Group. Consequently, repository interfaces for the Customer module are:</p>
-<ul>
-   <li><code>CustomerRepositoryInterface</code></li>
-   <li><code>AddressRepositoryInterface</code></li>
-   <li><code>GroupRepositoryInterface</code></li>
-</ul>
-<p>Repository interfaces must provide these functions:</p>
+Repository interfaces provide access to persistent data entities.
+
+For example, persistent data entities for the Customer module include Customer, Address, and Group. Consequently, repository interfaces for the Customer module are:
+
+- `CustomerRepositoryInterface`
+- `AddressRepositoryInterface`
+- `GroupRepositoryInterface`
+
+Repository interfaces must provide these functions:
+
 <table style="width:100%">
    <tr bgcolor="lightgray">
       <th>Function</th>
@@ -108,11 +114,13 @@ Service contract data interfaces are now mutable.
       </td>
    </tr>
 </table>
-<p>Each data entity has a corresponding interface. Consequently, the <code>get()</code> function in the corresponding interface, for example, can return the exact type.</p>
+
+Each data entity has a corresponding interface. Consequently, the `get()` function in the corresponding interface, for example, can return the exact type.
 
 ### Management interfaces {#management-interfaces}
 
-<p>Management interfaces provide management functions that are not related to repositories. For example:</p>
+Management interfaces provide management functions that are not related to repositories. For example:
+
 <table style="width:100%">
    <tr bgcolor="lightgray">
       <th>Interface</th>
@@ -138,8 +146,5 @@ Service contract data interfaces are now mutable.
 
 ### Related topics {#related-topics}
 
-<ul>
-   <li><a href="{{ page.baseurl }}/extension-dev-guide/service-contracts/service-contracts.html">Service contracts</a></li>
-   <li><a href="{{ page.baseurl }}/extension-dev-guide/service-contracts/service-to-web-service.html">Configure services as web APIs</a>
-   </li>
-</ul>
+- [Service contracts]({{ page.baseurl }}/extension-dev-guide/service-contracts/service-contracts.html)
+- [Configure services as web APIs]({{ page.baseurl }}/extension-dev-guide/service-contracts/service-to-web-service.html)
diff --git a/guides/v2.2/extension-dev-guide/service-contracts/service-contracts.md b/guides/v2.2/extension-dev-guide/service-contracts/service-contracts.md
index bf87529cf59..aece9f2f3d6 100644
--- a/guides/v2.2/extension-dev-guide/service-contracts/service-contracts.md
+++ b/guides/v2.2/extension-dev-guide/service-contracts/service-contracts.md
@@ -16,24 +16,23 @@ To address these issues, the Magento system introduces _service contracts_.
 
 ## What is a service contract? {#what-is-msc}
 
-<p>A [service contract](https://glossary.magento.com/service-contract) is a set of [PHP](https://glossary.magento.com/php) interfaces that are defined for a [module](https://glossary.magento.com/module).
-   A service contract includes <a href="{{ page.baseurl }}/extension-dev-guide/service-contracts/design-patterns.html#data-interfaces">data interfaces</a>, which preserve data integrity, and <a href="{{ page.baseurl }}/extension-dev-guide/service-contracts/design-patterns.html#service-interfaces">service interfaces</a>, which hide business logic details from service requestors such as controllers, web services, and other modules.
-</p>
-<p>If developers define data and service interfaces according to a set of <a href="{{ page.baseurl }}/extension-dev-guide/service-contracts/design-patterns.html">design patterns</a>, the result is a well-defined, durable [API](https://glossary.magento.com/api) that other modules and third-party extensions can implement through Magento models and resource models.
-</p>
-<p><img src="{{ site.baseurl }}/common/images/msc.jpg"/></p>
+A [service contract](https://glossary.magento.com/service-contract) is a set of [PHP](https://glossary.magento.com/php) interfaces that are defined for a [module](https://glossary.magento.com/module).
+A service contract includes [data interfaces]({{ page.baseurl }}/extension-dev-guide/service-contracts/design-patterns.html#data-interfaces), which preserve data integrity, and [service interfaces]({{ page.baseurl }}/extension-dev-guide/service-contracts/design-patterns.html#service-interfaces), which hide business logic details from service requestors such as controllers, web services, and other modules.
+
+If developers define data and service interfaces according to a set of [design patterns]({{ page.baseurl }}/extension-dev-guide/service-contracts/design-patterns.html), the result is a well-defined, durable [API](https://glossary.magento.com/api) that other modules and third-party extensions can implement through Magento models and resource models.
+
+![Service Contracts]({{ site.baseurl }}/common/images/msc.jpg)
 
 ## Service contract benefits {#msc-benefits}
 
-<p>Service contracts enhance the modularity of Magento. They enable Magento and third-party developers to report system dependencies through <b>composer.json</b> files and, consequently, guarantee compatibility among Magento versions. This compatibility ensures that merchants can easily upgrade Magento.</p>
-<p>These contracts ensure a well-defined, durable API that other modules and third-party extensions can implement. Also, these contracts make it easy to <a href="{{ page.baseurl }}/extension-dev-guide/service-contracts/service-to-web-service.html">configure services as web APIs</a>.
-</p>
-<p>Data entities are a side benefit of service contracts.
-   The database tables that normally support these entities can be complicated.
-   For example, some attributes might be stored in an EAV table, so a set of MySQL database tables might define a single data [entity](https://glossary.magento.com/entity).
-   Data entities in a service contract reveal a simpler data model than the data model in an underlying relational [database schema](https://glossary.magento.com/database-schema).
-   Eventually, you will be able to use different storage technologies for different data collections. For example, you could use a NoSQL database to replace product tables.
-</p>
+Service contracts enhance the modularity of Magento. They enable Magento and third-party developers to report system dependencies through `composer.json` files and, consequently, guarantee compatibility among Magento versions. This compatibility ensures that merchants can easily upgrade Magento.
+These contracts ensure a well-defined, durable API that other modules and third-party extensions can implement. Also, these contracts make it easy to [configure services as web APIs]({{ page.baseurl }}/extension-dev-guide/service-contracts/service-to-web-service.html).
+
+Data entities are a side benefit of service contracts.
+The database tables that normally support these entities can be complicated.
+For example, some attributes might be stored in an EAV table, so a set of MySQL database tables might define a single data [entity](https://glossary.magento.com/entity).
+Data entities in a service contract reveal a simpler data model than the data model in an underlying relational [database schema](https://glossary.magento.com/database-schema).
+Eventually, you will be able to use different storage technologies for different data collections. For example, you could use a NoSQL database to replace product tables.
 
 ## Using the @api tag
 
@@ -41,5 +40,5 @@ Backward compatibility can be indicated by the use of `@api`. For more informati
 
 ### Related topics {#related-topics}
 
-- [Service contract designpatterns]({{ page.baseurl }}/extension-dev-guide/service-contracts/design-patterns.html)
+- [Service contract design patterns]({{ page.baseurl }}/extension-dev-guide/service-contracts/design-patterns.html)
 - [Configure services as webAPIs]({{ page.baseurl }}/extension-dev-guide/service-contracts/service-to-web-service.html)

From ad2d83f10733833cd387e7c58dfb92f60de46989 Mon Sep 17 00:00:00 2001
From: Kevin Harper <keharper@adobe.com>
Date: Mon, 15 Jul 2019 19:32:11 -0500
Subject: [PATCH 2/2] fix broken link

---
 .../extension-dev-guide/service-contracts/design-patterns.md    | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/guides/v2.2/extension-dev-guide/service-contracts/design-patterns.md b/guides/v2.2/extension-dev-guide/service-contracts/design-patterns.md
index 3af8925835f..d50f1a3de4e 100644
--- a/guides/v2.2/extension-dev-guide/service-contracts/design-patterns.md
+++ b/guides/v2.2/extension-dev-guide/service-contracts/design-patterns.md
@@ -49,7 +49,7 @@ Service interfaces include several interface subtypes:
 - Management interfaces
 - Metadata interfaces
 
-For file names and coding standards, follow the defined [PHP coding standards]("{{ page.baseurl }}/coding-standards/code-standard-php.html).
+For file names and coding standards, follow the defined [PHP coding standards]({{ page.baseurl }}/coding-standards/code-standard-php.html).
 
 Place service interfaces in the top-level `Api` directory for a module.