Updated Using Templates (markdown)

Using-Templates.md

@@ -1,32 +1,32 @@
-You can use templates in the articles for commonly repeated content in multiple documents. Templates ease the support of the documentation. 
+In articles, you can use templates for commonly repeated content in multiple documents. Templates ease the support of the documentation. 
 
 ## In-article Syntax
 
 The plugin will capture the following syntax and replace it with the corresponding template:
 
-> Example 1: In-article Template syntax.
+> Example 1: In-article Template syntax
 
 ````
 @[template - info](/path/to/file.md#template_id "argument: value")
 ````
 
-You can break it into five parts:
+You can break the code line into the following parts:
 
-1. `@[template`—indicates that this will be rendered from a template;
-1. `- info]`—(*optional*) small description;
-1. `(/path/to/file.md`—indicates in which file the template is located;
-1. `#template_id`—indicates the section of the exact template to be put;
-1. `"argument: value")`—(*optional*) arguments which to be replaced later in the generated content.
+1. `@[template`—Indicates that this will be rendered from a template.
+1. (Optional) `- info]`—A short description.
+1. `(/path/to/file.md`—Indicates in which file the template is located.
+1. `#template_id`—Indicates the section of the exact template that will be used.
+1. (Optional) `"argument: value")`—Arguments that will be replaced later in the generated content.
 
-The syntax follows the native Markdown syntax for link. By that, in GitHub, a link to the template is rendered. 
+The syntax follows the native Markdown syntax for links. By that, in GitHub, a link to the template is rendered. 
 
 ## Creating Templates 
 
-The template files are located in the `_template` folder of ajax-docs repo. Inside this folder, new template files can be put in any folder structure that is required.
+Place the template files in a `_template` folder of the docs repo. Inside this folder, you can create an inner folder structure and place new template files whenever required.
 
 Creating a template also follows the Markdown specification and syntax. 
 
-> Example 2: Syntax for creating templates.
+> Example 2: Syntax for creating templates
 
 ````
 #section-id
@@ -36,7 +36,7 @@ You can write here plain Markdown.
 
 ## Using Arguments
 
-With the templates you can also use arguments in order to change the contents of the generated Markdown according to the context of the article.   
+With the templates you can also use arguments to change the contents of the generated Markdown according to the context of the article.   
 
 > Example 3: Using arguments
 
@@ -52,7 +52,7 @@ As of **@{version}** **@{control}** exposes this new feature.
 #end
 ````
 
-With the build of the documentation, the setup from **Example 3** will generate the following Markdown:
+With the building of the documentation, the setup from **Example 3** will generate the following Markdown:
 
 > Example 4: The result of Example 3
 
@@ -62,9 +62,9 @@ As of **Q1 2016** **RadControl** exposes this new feature.
 
 ## Reusing Templates 
 
-There are cases where the template should be quite different in terms of Markdown contents. For such cases you can reuse templates (i.e., nest them inside other templates).
+Sometimes the template has to be quite different in terms of Markdown contents. For such cases you can reuse templates (that is, nest them inside other templates).
 
-For example, you have two text instances that are the same and the only difference is that some piece of text should be linked only in one article. You can use a template as a base, and create two more to extend the base and use it in the articles. 
+For example, you have two text instances that are the same and the only difference is that some piece of text has to be linked only in one article. You can use a template as a base, and create two more to extend the base and use them in the articles. 
 
 > Example 5: Reusing templates
 
@@ -93,7 +93,7 @@ This new control exposes
 #
 ````
 
-And the following Markdown will be generated for the two articles:
+The following Markdown will be generated for the two articles:
 
 > Example 6: The results from Example 5
 
@@ -109,18 +109,18 @@ This new control exposes [Lightweight rendering]({%slug slug/link%}).
 
 ## Examples
 
-You can find here real life examples of templates used in our documentation:
+Real-life examples of templates in the Telerik documentation:
 
 * Reusing templates ([see commit](https://github.com/telerik/ajax-docs/commit/a9a7dbb51c94806872018f7a44721379767cc7c5)):
-    * The template file: [wai-aria-templates.md](https://github.com/telerik/ajax-docs/blob/master/_templates/common/wai-aria-templates.md);
-    * Checkbox - [wai-aria-support.md](https://github.com/telerik/ajax-docs/blob/master/controls/checkbox/accessibility-and-internationalization/wai-aria-support.md)
-    * DropDownList - [wai-aria-support.md](https://github.com/telerik/ajax-docs/blob/master/controls/dropdownlist/accessibility-and-internationalization/wai-aria-support.md)
-    * Editor - [wai-aria-support.md](https://github.com/telerik/ajax-docs/blob/master/controls/editor/accessibility-and-internationalization/standards-compliance/wai-aria-support.md)
-    * RadWindow - [wai-aria-support.md](https://github.com/telerik/ajax-docs/blob/master/controls/window/accessibility-and-internationalization/wai-aria-support.md)
+    * The template file: [wai-aria-templates.md](https://github.com/telerik/ajax-docs/blob/master/_templates/common/wai-aria-templates.md).
+    * Checkbox [`wai-aria-support.md`](https://github.com/telerik/ajax-docs/blob/master/controls/checkbox/accessibility-and-internationalization/wai-aria-support.md).
+    * DropDownList [`wai-aria-support.md`](https://github.com/telerik/ajax-docs/blob/master/controls/dropdownlist/accessibility-and-internationalization/wai-aria-support.md).
+    * Editor [`wai-aria-support.md`](https://github.com/telerik/ajax-docs/blob/master/controls/editor/accessibility-and-internationalization/standards-compliance/wai-aria-support.md).
+    * RadWindow [`wai-aria-support.md`](https://github.com/telerik/ajax-docs/blob/master/controls/window/accessibility-and-internationalization/wai-aria-support.md).
 
 ## Good Practices 
 
-* Although you can add info in `@[template]` keep it as short as possible. If you tend to write long info consider adding description in HTML comments. It will be easier to read. 
+* Although you can add more information in `@[template]`, keep the content as short as possible. If you tend to write long pieces of information, consider adding a description in HTML comments. It will be easier to read. 
 
-* [Liquid tags](https://github.com/Shopify/liquid/wiki/Liquid-for-Designers) are supported in the templates' content. If a certain template should use large amount of arguments, consider using [Liquid variables](https://github.com/Shopify/liquid/wiki/Liquid-for-Designers#variable-assignment) to shorten the Template declaration in the article's markup.
+* The templates support [Liquid tags](https://github.com/Shopify/liquid/wiki/Liquid-for-Designers). If a certain template has to use a large number of arguments, consider using [Liquid variables](https://github.com/Shopify/liquid/wiki/Liquid-for-Designers#variable-assignment) to shorten the Template declaration in the markup of the article.