Merge branch 'docs/instance-template-refactor' into 'master'

Refactor the instance-wide custom templates docs

See merge request gitlab-org/gitlab-ee!7459

doc/user/admin_area/settings/index.md

@@ -13,6 +13,7 @@ include:
 - [Third party offers](third_party_offers.md)
 - [Usage statistics](usage_statistics.md)
 - [Visibility and access controls](visibility_and_access_controls.md)
+- [Custom templates repository](instance_template_repository.md)
 
 ## GitLab.com admin area settings
 

doc/user/admin_area/settings/instance_template_repository.md

-# Instance-level Template Repository
+# Instance-level template repository **[PREMIUM ONLY]**
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/5986) in
 > [GitLab Premium](https://about.gitlab.com/pricing) 11.3.
@@ -7,35 +7,35 @@
 
 In hosted systems, enterprises often have a need to share their own templates
 across teams. This feature allows an administrator to pick a project to be the
-instance-wide collection of templates. These templates are then exposed to all
-users while the project remains secure. Currently supported templates: Licenses.
+instance-wide collection of file templates. These templates are then exposed to
+all users [via the web editor](../../project/repository/web_editor.md#template-dropdowns)
+while the project remains secure.
 
 ## Configuration
 
-An administrator can choose any project to be the template repository. This is
-done through the `Settings` page in the `Admin Area` or through the API. On the
-`Settings` page, there is a `Templates` section with a selection box for
-choosing a project:
+As an administrator, navigate to **Admin area > Settings > Templates** and
+select the project to serve as the custom template repository.
 
-![](img/file_template_admin_area.png)
+![File templates in the admin area](img/file_template_admin_area.png)
 
+Once a project has been selected, you can add custom templates to the repository,
+and they will appear in the appropriate places in the
+[frontend](../../project/repository/web_editor.md#template-dropdowns) and
+[API](../../../api/settings.md).
 
-Once a project has been selected you can add custom templates to the repository,
-and they will appear in the appropriate places in the frontend and API.
 Templates must be added to a specific subdirectory in the repository,
-corresponding to the kind of template. They must also have the correct extension
-for the template type.
+corresponding to the kind of template. The following types of custom templates
+are supported:
 
-Currently, the following types of custom template are supported:
+| Type              | Directory     | Extension     |
+| :---------------: | :-----------: | :-----------: |
+| `Dockerfile`      | `Dockerfile`  | `.dockerfile` |
+| `.gitignore`      | `gitignore`   | `.gitignore`  |
+| `.gitlab-ci.yml`  | `gitlab-ci`   | `.yml`        |
+| `LICENSE`         | `LICENSE`     | `.txt`        |
 
-* `Dockerfile`: `Dockerfile` directory, `.dockerfile` extension
-* `.gitignore`: `gitignore` directory, `.gitignore` extension
-* `.gitlab-ci.yml`: `gitlab-ci` directory, `.yml` extension
-* `LICENSE`: `LICENSE` directory, `.txt` extension
-
-Each template must go in its respective subdirectory and have the correct
-extension. So, the hierarchy
-should look like this:
+Each template must go in its respective subdirectory, have the correct
+extension and not be empty. So, the hierarchy should look like this:
 
 ```text
 |-- README.md
@@ -53,11 +53,11 @@ should look like this:
     |-- another_license.txt
 ```
 
-Once this is established, the list of `Custom` licenses will be included when
-creating a new file and the file type is `License`. These will appear at the
-bottom of the list:
+Once this is established, the list of custom templates will be included when
+creating a new file and the template type is selected. These will appear at the
+top of the list.
 
-![](img/file_template_user_dropdown.png)
+![Custom template dropdown menu](img/file_template_user_dropdown.png)
 
-If this feature has been disabled or no licenses are present, then there will be
-no `Custom` section in the selection dropdown.
+If this feature is disabled or no templates are present, there will be
+no "Custom" section in the selection dropdown.

doc/user/project/repository/web_editor.md

@@ -33,13 +33,13 @@ easy for you.
 
 ![First file for your project](img/web_editor_template_dropdown_first_file.png)
 
-When clicking on either `LICENSE` or `.gitignore`, a dropdown will be displayed
+When clicking on either `LICENSE` or `.gitignore`, etc., a dropdown will be displayed
 to provide you with a template which might be suitable for your project.
 
 ![MIT license selected](img/web_editor_template_dropdown_mit_license.png)
 
 The license, changelog, contribution guide, or `.gitlab-ci.yml` file could also
-be added through a button on the project page. In the example below the license
+be added through a button on the project page. In the example below, the license
 has already been created, which creates a link to the license itself.
 
 ![New file button](img/web_editor_template_dropdown_buttons.png)

ee/app/views/admin/application_settings/_templates.html.haml

@@ -16,7 +16,7 @@
             = f.label :file_template_project_id, class: 'label-light' do
               .form-text.text-muted
                 Select a
-                = link_to 'template repository', help_page_path("user/admin_area/settings/instance_template_repository", anchor: "version-check")
+                = link_to 'template repository', help_page_path("user/admin_area/settings/instance_template_repository")
             = project_select_tag('application_setting[file_template_project_id]', class: 'project-item-select hidden-filter-value', toggle_class: 'js-project-search js-project-filter js-filter-submit', dropdown_class: 'dropdown-menu-selectable dropdown-menu-project js-filter-submit',
               placeholder: admin_project_dropdown_label('Search projects'), idAttribute: 'id', data: { order_by: 'last_activity_at', idattribute: 'id', all_projects: 'true', simple_filter: true, allow_clear: true}, value: @application_setting.file_template_project_id)
         = f.submit 'Save changes', class: "btn btn-success"