Merge branch 'docs/document-built-in-templates' into 'master'

Restructure projects template topics

Closes #55834

See merge request gitlab-org/gitlab-ce!24448

5 files changed, 102 insertions, 47 deletions

diff --git a/doc/gitlab-basics/create-project.md b/doc/gitlab-basics/create-project.md
index 33f46e8d4f3..978ffde84ad 100644
--- a/doc/gitlab-basics/create-project.md
+++ b/doc/gitlab-basics/create-project.md
@@ -1,27 +1,28 @@
-# How to create a project in GitLab
+# Create a project
 
-> **Notes:**
-> - For a list of words that are not allowed to be used as project names see the
->   [reserved names][reserved].
+[Projects](../user/project/index.md) combine many features of GitLab together.
 
-1. In your dashboard, click the green **New project** button or use the plus
-   icon in the upper right corner of the navigation bar.
+NOTE: **Note:**
+For a list of words that cannot be used as project names see
+[Reserved project and group names](../user/reserved_names.md).
 
-    ![Create a project](img/create_new_project_button.png)
+To create a project in GitLab:
 
-1. This opens the **New project** page.
+1. In your dashboard, click the green **New project** button or use the plus
+   icon in the navigation bar. This opens the **New project** page.
+1. On the **New project** page, choose if you want to:
+   - Create a [blank project](#blank-projects).
+   - Create a project using with one of the available [project templates](#project-templates).
+   - [Import a project](../user/project/import/index.md) from a different repository,
+     if enabled on your GitLab instance. Contact your GitLab admin if this
+     is unavailable.
 
-    ![Project information](img/create_new_project_info.png)
+## Blank projects
 
-1. Choose if you want start a blank project, or with one of the predefined
-   [Project Templates](https://gitlab.com/gitlab-org/project-templates):
-   this will kickstart your repository code and CI automatically.
-   Otherwise, if you have a project in a different repository, you can [import it] by
-   clicking on the **Import project** tab, provided this is enabled in
-   your GitLab instance. Ask your administrator if not.
+To create a new blank project on the **New project** page:
 
-1. Provide the following information:
-    - Enter the name of your project in the **Project name** field. You can't use
+1. On the **Blank project** tab, provide the following information:
+    - The name of your project in the **Project name** field. You can't use
       special characters, but you can use spaces, hyphens, underscores or even
       emoji.
     - The **Project description (optional)** field enables you to enter a
@@ -31,11 +32,64 @@
     - Changing the **Visibility Level** modifies the project's
       [viewing and access rights](../public_access/public_access.md) for users.
     - Selecting the **Initialize repository with a README** option creates a
-      README so that the Git repository is initialized, has a default branch and
+      README file so that the Git repository is initialized, has a default branch, and
       can be cloned.
-
 1. Click **Create project**.
 
+## Project templates
+
+Project templates can pre-populate your project with necessary files to get you started quickly.
+
+There are two types of project templates:
+
+- [Built-in templates](#builtin-templates), sourced from the [`project-templates`](https://gitlab.com/gitlab-org/project-templates) group.
+- [Custom project templates](#custom-project-templates-premium-only), for custom templates configured by GitLab administrators and users.
+
+### Built-in templates
+
+Built-in templates are project templates that are:
+
+- Developed and maintained in the
+  [`project-templates`](https://gitlab.com/gitlab-org/project-templates) group.
+- Released with GitLab.
+
+To use a built-in template on the **New project** page:
+
+1. On the **Create from template** tab.
+1. From the list of available built-in templates, click the:
+    - **Preview** button to look at the template source itself.
+    - **Use template** button to start creating the project.
+1. Finish creating the project by filling out the project's details. The process is the same as for
+   using a [blank project](#blank-projects).
+
+TIP: **Tip:**
+You can improve the existing built-in templates or contribute new ones on the
+[`project-templates`](https://gitlab.com/gitlab-org/project-templates) group.
+
+### Custom project templates **[PREMIUM ONLY]**
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/6860) in
+[GitLab Premium](https://about.gitlab.com/pricing) 11.2.
+
+Creating new projects based on custom project templates is a convenient option to bootstrap a project.
+
+Custom projects are available from the **Instance** or **Group** tabs under the **Create from template** tab,
+depending on the type of template.
+
+To use a custom project template on the **New project** page:
+
+1. On the **Create from template** tab, select the **Instance** tab or the **Group** tab.
+1. From the list of available custom templates, click the:
+    - **Preview** button to look at the template source itself.
+    - **Use template** button to start creating the project.
+1. Finish creating the project by filling out the project's details. The process is the same as for
+   using a [blank project](#blank-projects).
+
+For information on configuring custom project templates, see:
+
+- [Custom instance-level project templates](../user/admin_area/custom_project_templates.md), for instance-level templates.
+- [Custom group-level project templates](../user/group/custom_project_templates.md), for group-level templates.
+
 ## Push to create a new project
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/26388) in GitLab 10.5.
@@ -46,20 +100,20 @@ GitLab to create the new project, all without leaving your terminal. If you have
 namespace, we will automatically create a new project under that GitLab namespace with its
 visibility set to Private by default (you can later change it in the [project's settings](../public_access/public_access.md#how-to-change-project-visibility)).
 
-This can be done by using either SSH or HTTP:
+This can be done by using either SSH or HTTPS:
 
-```
+```sh
 ## Git push using SSH
 git push --set-upstream git@gitlab.example.com:namespace/nonexistent-project.git master
 
-## Git push using HTTP
+## Git push using HTTPS
 git push --set-upstream https://gitlab.example.com/namespace/nonexistent-project.git master
 ```
 
 Once the push finishes successfully, a remote message will indicate
 the command to set the remote and the URL to the new project:
 
-```
+```text
 remote:
 remote: The private project namespace/nonexistent-project was created.
 remote:
@@ -70,6 +124,3 @@ remote: To view the project, visit:
 remote:   https://gitlab.example.com/namespace/nonexistent-project
 remote:
 ```
-
-[import it]: ../workflow/importing/README.md
-[reserved]:  ../user/reserved_names.md
diff --git a/doc/gitlab-basics/img/create_new_project_button.png b/doc/gitlab-basics/img/create_new_project_button.png
deleted file mode 100644
index 567f104880f..00000000000
--- a/doc/gitlab-basics/img/create_new_project_button.png
+++ /dev/null
diff --git a/doc/gitlab-basics/img/create_new_project_info.png b/doc/gitlab-basics/img/create_new_project_info.png
deleted file mode 100644
index 2693a7f9a6d..00000000000
--- a/doc/gitlab-basics/img/create_new_project_info.png
+++ /dev/null
diff --git a/doc/user/admin_area/custom_project_templates.md b/doc/user/admin_area/custom_project_templates.md
index 5afbf9f2934..e34ba045c54 100644
--- a/doc/user/admin_area/custom_project_templates.md
+++ b/doc/user/admin_area/custom_project_templates.md
@@ -2,24 +2,25 @@
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/6860) in [GitLab Premium](https://about.gitlab.com/pricing) 11.2.
 
-When you create a new project, creating it based on custom project templates is
-a convenient option to bootstrap from an existing project boilerplate.
-The administration setting to configure a GitLab group that serves as template
-source can be found under **Admin > Settings > Custom project templates**.
+When you create a new [project](../project/index.md), creating it based on custom project templates is
+a convenient bootstrap option.
+
+GitLab administrators can configure a GitLab group that serves as template
+source for an entire GitLab instance under **Admin area > Settings > Custom project templates**.
+
+NOTE: **Note:**
+To set project templates at a group level,
+see [Custom group-level project templates](../group/custom_project_templates.md).
 
 Within this section, you can configure the group where all the custom project
 templates are sourced. Every project directly under the group namespace will be
 available to the user if they have access to them. For example, every public
-project in the group will be available to every logged user. However,
-private projects will be available only if the user has view [permissions](../permissions.md)
-in the project:
+project in the group will be available to every logged in user.
 
-- Project Owner, Maintainer, Developer, Reporter or Guest
-- Is a member of the Group: Owner, Maintainer, Developer, Reporter or Guest
+However, private projects will be available only if the user is a member of the project.
 
+NOTE: **Note:**
 Projects below subgroups of the template group are **not** supported.
 
 Repository and database information that are copied over to each new project are
 identical to the data exported with [GitLab's Project Import/Export](../project/settings/import_export.md).
-
-If you would like to set project templates at a group level, please see [Custom group-level project templates](../group/custom_project_templates.md).
\ No newline at end of file
diff --git a/doc/user/group/custom_project_templates.md b/doc/user/group/custom_project_templates.md
index eaf0273050b..8e101407ac0 100644
--- a/doc/user/group/custom_project_templates.md
+++ b/doc/user/group/custom_project_templates.md
@@ -2,22 +2,25 @@
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/6861) in [GitLab Premium](https://about.gitlab.com/pricing) 11.6.
 
-When you create a new project, creating it based on custom project templates is
-a convenient option to bootstrap from an existing project boilerplate.
-The group-level setting to configure a GitLab group that serves as template
-source can be found under **Group > Settings > General > Custom project templates**.
+When you create a new [project](../project/index.md), creating it based on custom project templates is
+a convenient bootstrap option.
+
+Users can configure a GitLab group that serves as template
+source under a group's **Settings > General > Custom project templates**.
+
+NOTE: **Note:**
+GitLab administrators can
+[set project templates for an entire GitLab instance](../admin_area/custom_project_templates.md).
 
 Within this section, you can configure the group where all the custom project
 templates are sourced. Every project directly under the group namespace will be
 available to the user if they have access to them. For example, every public
-project in the group will be available to every logged in user. However,
-private projects will be available only if the user has view [permissions](../permissions.md)
-in the project. That is, users with Owner, Maintainer, Developer, Reporter or Guest roles for projects,
-or for groups to which the project belongs.
+project in the group will be available to every logged in user.
 
+However, private projects will be available only if the user is a member of the project.
+
+NOTE: **Note:**
 Projects of nested subgroups of a selected template source cannot be used.
 
 Repository and database information that are copied over to each new project are
 identical to the data exported with [GitLab's Project Import/Export](../project/settings/import_export.md).
-
-If you would like to set project templates at an instance level, please see [Custom instance-level project templates](../admin_area/custom_project_templates.md).
\ No newline at end of file