version 2

articles/modeling/reference-spec.md

@@ -4,41 +4,50 @@
 
 ## What
 
-Depending on your use case, you may find yourself needing to reference or connect to another spec or part of your current one.
+Referencing another specification allows for cleaner and more organized code. Some use cases are as follows...
 
-This can be done easily for another specification in your project, one that has been publicly shared, one from an external source, or even reference certain targets within your current specification.
-
-Reasons for referencing another specification include generating documentaion in hubs from an oas file, deduplicating common structures in modeling, testing a connected specification in scenarios, or setting up a mock server for an API.
+* Generate API documentaion in Hubs
+* Deduplicate common structures like responses or shared parameters in Modeling
+* Test a connected API specification in Scenarios
+* Setup a mock server for an API in Prism
 
 ## How
 
-1.  Choose the appropriate data source.
+1.  Choose the **source**.
 
     * This File
 
     * This Project
 
+      * Select a **file**.
 
-      * Shared/Common
+    * Shared/Common
 
-      * External URL
+    * External URL
 
-2.  Select a file or enter a valid url that contains data for an existing specification.
+      * Enter a valid **URL** to an existing specification.
 
-3.  Select a target, if required or applicable.
+2.  Select a **target**, if required.
 
-4.  Confirm your choice, if you see a confirm button.
+3.  Confirm your choice. (Only required if there is a confirm button)
 
-5.  View the referenced specification by clicking the book icon.
+4.  View the referenced specification by clicking the book icon.
 
-## Where
+## Related Links
 
-* Documentation
-  * [Reference other Sources](../hubs/ref-other-sources-hubs.md)
-* Modeling
-  * [Creating Models](../modeling/how-to-create-models.md#How-to-Create-Models-using-the-Stoplight-Modeling-Editor)
-  * [Shared Parameters and Responses](../modeling/shared-params-responses.md)
-* Testing
-  * [Contract Testing](../testing/contract-testing.md#connecting-the-spec)
-* Mocking
-  * [Setting Up a Prism Mock Server](../prism/mocking.md)
+Documentation
+
+* [Reference other Sources](../hubs/ref-other-sources-hubs.md)
+
+Modeling
+
+* [Creating Models](../modeling/how-to-create-models.md#How-to-Create-Models-using-the-Stoplight-Modeling-Editor)
+* [Shared Parameters and Responses](../modeling/shared-params-responses.md)
+
+Testing
+
+* [Contract Testing](../testing/contract-testing.md#connecting-the-spec)
+
+Mocking
+
+* [Setting Up a Prism Mock Server](../prism/mocking.md)