Merge branch 'docs/ssot-university-topics' into 'master'

SSoT audit fixes for some topics in GitLab U section

Closes #61513

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

doc/administration/index.md

@@ -36,7 +36,7 @@ Learn how to install, configure, update, and maintain your GitLab instance.
   - [Omnibus support for external MySQL DB](https://docs.gitlab.com/omnibus/settings/database.html#using-a-mysql-database-management-server-enterprise-edition-only): Omnibus package supports configuring an external MySQL database. **[STARTER ONLY]**
   - [Omnibus support for log forwarding](https://docs.gitlab.com/omnibus/settings/logs.html#udp-log-shipping-gitlab-enterprise-edition-only) **[STARTER ONLY]**
 - [High Availability](high_availability/README.md): Configure multiple servers for scaling or high availability.
-  - [High Availability on AWS](../university/high-availability/aws/README.md): Set up GitLab HA on Amazon AWS.
+  - [Installing GitLab HA on Amazon Web Services (AWS)](../install/aws/index.md): Set up GitLab High Availability on Amazon AWS.
 - [Geo](geo/replication/index.md): Replicate your GitLab instance to other geographic locations as a read-only fully operational version. **[PREMIUM ONLY]**
 - [Disaster Recovery](geo/disaster_recovery/index.md): Quickly fail-over to a different site with minimal effort in a disaster situation. **[PREMIUM ONLY]**
 - [Pivotal Tile](../install/pivotal/index.md): Deploy GitLab as a pre-configured appliance using Ops Manager (BOSH) for Pivotal Cloud Foundry. **[PREMIUM ONLY]**

doc/university/bookclub/booklist.md

 ---
 comments: false
+type: index
 ---
 
 # Books
 
-List of books and resources, that may be worth reading.
+List of books and resources that may be worth reading.
 
 ## Papers
 

doc/university/bookclub/index.md

 ---
 comments: false
+type: index
 ---
 
 # The GitLab Book Club

doc/university/support/README.md

 ---
 comments: false
+type: reference
 ---
 
 # Support Boot Camp
 
 **Goal:** Prepare new Service Engineers at GitLab
 
-For each stage there are learning goals and content to support the learning of the engineer.
+For each stage, there are learning goals and content to support the learning of the engineer.
 The goal of this boot camp is to have every Service Engineer prepared to help our customers
 with whatever needs they might have and to also assist our awesome community with their
 questions.
@@ -15,7 +16,7 @@ Always start with the [University Overview](../README.md) and then work
 your way here for more advanced and specific training. Once you feel comfortable
 with the topics of the current stage, move to the next.
 
-### Stage 1
+## Stage 1
 
 Follow the topics on the [University Overview](../README.md), concentrate on it
 during your first Stage, but also:
@@ -23,22 +24,22 @@ during your first Stage, but also:
 - Perform the [first steps](https://about.gitlab.com/handbook/support/onboarding/#first-steps) of
    the on-boarding process for new Service Engineers
 
-#### Goals
+### Goals
 
 Aim to have a good overview of the Product and main features, Git and the Company
 
-### Stage 2
+## Stage 2
 
 Continue to look over remaining portions of the [University Overview](../README.md) and continue on to these topics:
 
-#### Set up your development machine
+### Set up your development machine
 
 Get your development machine ready to familiarize yourself with the codebase, the components, and to be prepared to reproduce issues that our users encounter
 
 - Install the [GDK](https://gitlab.com/gitlab-org/gitlab-development-kit)
   - [Set up OpenLDAP as part of this](https://gitlab.com/gitlab-org/gitlab-development-kit#openldap)
 
-#### Become comfortable with the Installation processes that we support
+### Become comfortable with the Installation processes that we support
 
 It's important to understand how to install GitLab in the same way that our users do. Try installing different versions and upgrading and downgrading between them. Installation from source will give you a greater understanding of the components that we employ and how everything fits together.
 
@@ -73,7 +74,7 @@ Sometimes we need to upgrade customers from old versions of GitLab to latest, so
     - (GitLab inc. only) Acquire and apply a license for the Enterprise Edition product, ask in #support
 - Perform a downgrade from [EE to CE](../../downgrade_ee_to_ce/README.md)
 
-#### Start to learn about some of the integrations that we support
+### Start to learn about some of the integrations that we support
 
 Our integrations add great value to GitLab. User questions often relate to integrating GitLab with existing external services and the configuration involved
 
@@ -83,16 +84,16 @@ Our integrations add great value to GitLab. User questions often relate to integ
   - [Jenkins](../../integration/jenkins.md)
   - [SAML](../../integration/saml.md)
 
-#### Goals
+### Goals
 
 - Aim to be comfortable with installation of the GitLab product and configuration of some of the major integrations
 - Aim to have an installation available for reproducing customer reports
 
-### Stage 3
+## Stage 3
 
-#### Understand the gathering of diagnostics for GitLab instances
+### Understand the gathering of diagnostics for GitLab instances
 
-- Learn about the GitLab checks that are available
+- Learn about the GitLab checks that are available:
   - [Environment Information and maintenance checks](../../raketasks/maintenance.md)
   - [GitLab check](../../raketasks/check.md)
   - Omnibus commands
@@ -100,11 +101,11 @@ Our integrations add great value to GitLab. User questions often relate to integ
     - [Starting and stopping services](https://gitlab.com/gitlab-org/omnibus-gitlab/blob/master/doc/maintenance/README.md#starting-and-stopping)
     - [Starting a rails console](https://gitlab.com/gitlab-org/omnibus-gitlab/blob/master/doc/maintenance/README.md#invoking-rake-tasks)
 
-#### Learn about the Support process
+### Learn about the Support process
 
 Zendesk is our Support Centre and our main communication line with our Customers. We communicate with customers through several other channels too
 
-- Familiarize yourself with ZenDesk
+- Familiarize yourself with ZenDesk:
   - [UI Overview](https://support.zendesk.com/hc/en-us/articles/203661806-Introduction-to-the-Zendesk-agent-interface)
   - [Updating Tickets](https://support.zendesk.com/hc/en-us/articles/212530318-Updating-and-solving-tickets)
   - [Working w/ Tickets](https://support.zendesk.com/hc/en-us/articles/203690856-Working-with-tickets) *Read: avoiding agent collision.*
@@ -140,7 +141,7 @@ Zendesk is our Support Centre and our main communication line with our Customers
   - Upgrade calls
   - Emergency calls
 
-#### Learn about the Escalation process for tickets
+### Learn about the Escalation process for tickets
 
 Some tickets need specific knowledge or a deep understanding of a particular component and will need to be escalated to a Senior Service Engineer or Developer
 
@@ -148,7 +149,7 @@ Some tickets need specific knowledge or a deep understanding of a particular com
 - Find the macros in Zendesk for ticket escalations
 - Take a look at the [GitLab.com Team page](https://about.gitlab.com/team/) to find the resident experts in their fields
 
-#### Learn about raising issues and fielding feature proposals
+### Learn about raising issues and fielding feature proposals
 
 - Understand what's in the pipeline and proposed features at GitLab: [Direction Page](https://about.gitlab.com/direction/)
 - Practice searching issues and filtering using [labels](https://gitlab.com/gitlab-org/gitlab-ce/labels) to find existing feature proposals and bugs
@@ -157,15 +158,15 @@ Some tickets need specific knowledge or a deep understanding of a particular com
 - Take a look at the [existing issue templates](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/CONTRIBUTING.md#issue-tracker) to see what is expected
 - Raise issues for bugs in a manner that would make the issue easily reproducible. A Developer or a contributor may work on your issue
 
-#### Goals
+### Goals
 
 - Aim to have a good understanding of the problems that customers are facing
 - Aim to have gained experience in scheduling and participating in calls with customers
 - Aim to have a good understanding of ticket flow through Zendesk and how to interact with our various channels
 
-### Stage 4
+## Stage 4
 
-#### Advanced GitLab topics
+### Advanced GitLab topics
 
 Move on to understanding some of GitLab's more advanced features. You can make use of GitLab.com to understand the features from an end-user perspective and then use your own instance to understand setup and configuration of the feature from an Administrative perspective
 
@@ -179,11 +180,23 @@ Move on to understanding some of GitLab's more advanced features. You can make u
      and the [CE codebase](https://gitlab.com/gitlab-org/gitlab-ce)
 - Ask as many questions as you can think of on the `#support` chat channel
 
-#### Get initiated for on-call duty
+### Get initiated for on-call duty
 
 - Read over the [public run-books to understand common tasks](https://gitlab.com/gitlab-com/runbooks)
 - Create an issue on the internal Organization tracker to schedule time with the DevOps / Production team, so that you learn how to handle GitLab.com going down. Once you are trained for this, you are ready to be added to the on-call rotation.
 
-#### Goals
+### Goals
 
 - Aim to become a fully-fledged Service Engineer!
+
+<!-- ## Troubleshooting
+
+Include any troubleshooting steps that you can foresee. If you know beforehand what issues
+one might have when setting this up, or when something is changed, or on upgrading, it's
+important to describe those, too. Think of things that may go wrong and include them here.
+This is important to minimize requests for support, and to avoid doc comments with
+questions that you know someone might ask.
+
+Each scenario can be a third-level heading, e.g. `### Getting error message X`.
+If you have none to add when creating a doc, leave this section in place
+but commented out to help encourage others to add to it in the future. -->

doc/university/training/gitlab_flow.md

 ---
 comments: false
+type: reference
 ---
 
 # What is the GitLab Flow
@@ -41,5 +42,17 @@ comments: false
 
 ## More details
 
-For more information read through the [GitLab Flow](../../workflow/gitlab_flow.md)
+For more information, read through the [GitLab Flow](../../workflow/gitlab_flow.md)
 documentation.
+
+<!-- ## Troubleshooting
+
+Include any troubleshooting steps that you can foresee. If you know beforehand what issues
+one might have when setting this up, or when something is changed, or on upgrading, it's
+important to describe those, too. Think of things that may go wrong and include them here.
+This is important to minimize requests for support, and to avoid doc comments with
+questions that you know someone might ask.
+
+Each scenario can be a third-level heading, e.g. `### Getting error message X`.
+If you have none to add when creating a doc, leave this section in place
+but commented out to help encourage others to add to it in the future. -->

doc/university/training/index.md

 ---
 comments: false
+type: index
 ---
 
 # GitLab Training Material
@@ -8,3 +9,34 @@ All GitLab training material is stored in markdown format. Slides are
 generated using [Deskset](http://www.decksetapp.com/).
 
 All training material is open to public contribution.
+
+This section contains the following topics:
+
+- [Agile and Git](topics/agile_git.md).
+- [Bisect](topics/bisect.md).
+- [Cherry pick](topics/cherry_picking.md).
+- [Code review and collaboration with Merge Requests](topics/merge_requests.md).
+- [Configure your environment](topics/env_setup.md).
+- [Explore GitLab](topics/explore_gitlab.md).
+- [Feature branching](topics/feature_branching.md).
+- [Getting started](topics/getting_started.md).
+- [GitLab flow](gitlab_flow.md).
+- [GitLab Git workshop](user_training.md).
+- [Git add](topics/git_add.md).
+- [Git introduction](topics/git_intro.md).
+- [Git log](topics/git_log.md).
+- [Git stash](topics/stash.md).
+- [Merge conflicts](topics/merge_conflicts.md).
+- [Rollback commits](topics/rollback_commits.md).
+- [Subtree](topics/subtree.md).
+- [Tags](topics/tags.md).
+- [Unstage](topics/unstage.md).
+
+## Additional Resources
+
+1. [GitLab Documentation](http://docs.gitlab.com)
+1. [GUI Clients](http://git-scm.com/downloads/guis)
+1. [Pro Git book](http://git-scm.com/book)
+1. [Platzi Course](https://courses.platzi.com/courses/git-gitlab/)
+1. [Code School tutorial](http://try.github.io/)
+1. Contact us at `subscribers@gitlab.com`

doc/university/training/topics/additional_resources.md

----
-comments: false
----
-
-# Additional Resources
-
-1. GitLab Documentation: <http://docs.gitlab.com>.
-1. GUI Clients: <http://git-scm.com/downloads/guis>.
-1. Pro Git book: <http://git-scm.com/book>.
-1. Platzi Course: <https://courses.platzi.com/courses/git-gitlab/>.
-1. Code School tutorial: <http://try.github.io/>.
-1. Contact us at `subscribers@gitlab.com`.

doc/university/training/topics/agile_git.md

@@ -4,22 +4,16 @@ comments: false
 
 # Agile and Git
 
-----------
-
 ## Agile
 
 Lean software development methods focused on collaboration and interaction
 with fast and smaller deployment cycles.
 
-----------
-
 ## Where Git comes in
 
 Git is an excellent tool for an Agile team considering that it allows
 decentralized and simultaneous development.
 
-----------
-
 ### Branching And Workflows
 
 Branching in an Agile environment usually happens around user stories with one
@@ -30,8 +24,7 @@ with his/her initials, and US id.
 
 After its tested merge into master and remove the branch.
 
-----------
-
 ## What about GitLab
+
 Tools like GitLab enhance collaboration by adding dialog around code mainly
 through issues and merge requests.

doc/university/training/topics/bisect.md

@@ -4,16 +4,12 @@ comments: false
 
 # Bisect
 
-----------
-
 ## Bisect
 
 - Find a commit that introduced a bug
 - Works through a process of elimination
 - Specify a known good and bad revision to begin
 
-----------
-
 ## Bisect
 
 1. Start the bisect process
@@ -23,11 +19,9 @@ comments: false
 1. Tell bisect the result
 1. Repeat the previous 2 items until you find the offending commit
 
-----------
-
 ## Setup
 
-```
+```sh
   mkdir bisect-ex
   cd bisect-ex
   touch index.html
@@ -44,9 +38,7 @@ comments: false
   vi index.html
 ```
 
-----------
-
-```
+```sh
   # Add all good 3
   git add -A
   git commit -m "fourth commit"
@@ -64,11 +56,9 @@ comments: false
   git commit -m "seventh commit"
 ```
 
-----------
-
 ## Commands
 
-```
+```sh
   git bisect start
   # Test your code
   git bisect bad

doc/university/training/topics/cherry_picking.md

@@ -4,16 +4,12 @@ comments: false
 
 # Cherry Pick
 
-----------
-
 ## Cherry Pick
 
 - Given an existing commit on one branch, apply the change to another branch
 - Useful for backporting bug fixes to previous release branches
 - Make the commit on the master branch and pick in to stable
 
-----------
-
 ## Cherry Pick
 
 1. Check out a new 'stable' branch from 'master'
@@ -23,8 +19,6 @@ comments: false
 1. Check out the 'stable' branch
 1. Cherry pick the commit using the SHA obtained earlier
 
-----------
-
 ## Commands
 
 ```bash

doc/university/training/topics/env_setup.md

@@ -4,7 +4,6 @@ comments: false
 
 # Configure your environment
 
-----------
 ## Install
 
 - **Windows**
@@ -22,8 +21,6 @@ comments: false
   sudo apt-get install git-all
   ```
 
-----------
-
 ## Configure Git
 
 One-time configuration of the Git client
@@ -33,8 +30,6 @@ git config --global user.name "Your Name"
 git config --global user.email you@example.com
 ```
 
-----------
-
 ## Configure SSH Key
 
 ```bash

doc/university/training/topics/explore_gitlab.md

@@ -4,8 +4,6 @@ comments: false
 
 # Explore GitLab projects
 
-----------
-
 - Dashboard
 - User Preferences
 - Issues

doc/university/training/topics/feature_branching.md

@@ -4,8 +4,6 @@ comments: false
 
 # Feature branching
 
-----------
-
 - Efficient parallel workflow for teams
 - Develop each feature in a branch
 - Keeps changes isolated
@@ -13,8 +11,6 @@ comments: false
 - Push branches to the server frequently
   - Hint: This is a cheap backup for your work-in-progress code
 
-----------
-
 ## Feature branching
 
 1. Create a new feature branch called 'squash_some_bugs'
@@ -22,11 +18,9 @@ comments: false
 1. Commit
 1. Push
 
-----------
-
 ## Commands
 
-```
+```sh
 git checkout -b squash_some_bugs
 # Edit `bugs.rb`
 git status

doc/university/training/topics/getting_started.md

@@ -4,8 +4,6 @@ comments: false
 
 # Getting Started
 
-----------
-
 ## Instantiating Repositories
 
 - Create a new repository by instantiating it through:
@@ -19,8 +17,6 @@ comments: false
     git clone <url>
     ```
 
-----------
-
 ## Central Repos
 
 - To instantiate a central repository a `--bare` flag is required.
@@ -31,8 +27,6 @@ comments: false
     git init --bare project-name.git
     ```
 
-----------
-
 ## Instantiate workflow with clone
 
 1. Create a project in your user namespace.
@@ -40,18 +34,15 @@ comments: false
 1. Create a '`Workspace`' directory in your home directory.
 1. Clone the '`training-examples`' project.
 
-----------
-
 ## Commands
 
-```
+```sh
 mkdir ~/workspace
 cd ~/workspace
 
 git clone git@gitlab.example.com:<username>/training-examples.git
 cd training-examples
 ```
-----------
 
 ## Git concepts
 
@@ -67,8 +58,6 @@ Files that have been modified but are not committed.
 
 Modified files that have been marked to go in the next commit.
 
-----------
-
 ## Committing Workflow
 
 1. Edit '`edit_this_file.rb`' in '`training-examples`'
@@ -79,11 +68,9 @@ Modified files that have been marked to go in the next commit.
 1. Push the commit to the remote
 1. View the git log
 
-----------
-
 ## Commands
 
-```
+```sh
 # Edit `edit_this_file.rb`
 git status
 git diff
@@ -93,8 +80,6 @@ git push origin master
 git log
 ```
 
-----------
-
 ## Note
 
 - git fetch vs pull

doc/university/training/topics/git_add.md

@@ -4,8 +4,6 @@ comments: false
 
 # Git Add
 
-----------
-
 ## Git Add
 
 Adds content to the index or staging area.
@@ -22,8 +20,6 @@ Adds content to the index or staging area.
     git add -A
     ```
 
-----------
-
 ## Git add continued
 
 - Add all text files in current dir:

doc/university/training/topics/git_intro.md

@@ -4,8 +4,6 @@ comments: false
 
 # Git introduction
 
-----------
-
 ## Intro
 
 <https://git-scm.com/about>
@@ -17,8 +15,6 @@ comments: false
 - Adapts to nearly any workflow
 - Fast, reliable and stable file format
 
-----------
-
 ## Help!
 
 Use the tools at your disposal when you get stuck.

doc/university/training/topics/git_log.md

@@ -4,44 +4,38 @@ comments: false
 
 # Git Log
 
-----------
-
 Git log lists commit history. It allows searching and filtering.
 
 - Initiate log:
 
-    ```
+    ```sh
     git log
     ```
 
 - Retrieve set number of records:
 
-    ```
+    ```sh
     git log -n 2
     ```
 
 - Search commits by author. Allows user name or a regular expression.
 
-    ```
+    ```sh
     git log --author="user_name"
     ```
 
-----------
-
 - Search by comment message:
 
-    ```
+    ```sh
     git log --grep="<pattern>"
     ```
 
 - Search by date:
 
-    ```
+    ```sh
     git log --since=1.month.ago --until=3.weeks.ago
     ```
 
-----------
-
 ## Git Log Workflow
 
 1. Change to workspace directory
@@ -51,11 +45,9 @@ Git log lists commit history. It allows searching and filtering.
 1. Search by date
 1. Combine
 
-----------
-
 ## Commands
 
-```
+```sh
 cd ~/workspace
 git clone git@gitlab.com:gitlab-org/gitlab-runner.git
 cd gitlab-runner

doc/university/training/topics/merge_conflicts.md

@@ -4,15 +4,11 @@ comments: false
 
 # Merge conflicts
 
-----------
-
 - Happen often
 - Learning to fix conflicts is hard
 - Practice makes perfect
 - Force push after fixing conflicts. Be careful!
 
-----------
-
 ## Merge conflicts
 
 1. Checkout a new branch and edit `conflicts.rb`. Add 'Line4' and 'Line5'.
@@ -26,11 +22,9 @@ comments: false
 1. Force push the changes.
 1. Finally continue with the Merge Request.
 
-----------
-
 ## Commands
 
-```
+```sh
 git checkout -b conflicts_branch
 
 # vi conflicts.rb
@@ -49,7 +43,7 @@ git push origin master
 
 Create a merge request on the GitLab web UI. You'll see a conflict warning.
 
-```
+```sh
 git checkout conflicts_branch
 git fetch
 git rebase master
@@ -65,7 +59,6 @@ git rebase --continue
 # need to force push so that our remote branch is restructured
 git push origin conflicts_branch -f
 ```
-----------
 
 ## Note
 

doc/university/training/topics/merge_requests.md

@@ -4,8 +4,6 @@ comments: false
 
 # Code review and collaboration with Merge Requests
 
-----------
-
 - When you want feedback create a merge request
 - Target is the default branch (usually master)
 - Assign or mention the person you would like to review
@@ -14,8 +12,6 @@ comments: false
 - Anyone can comment, not just the assignee
 - Push corrections to the same branch
 
-----------
-
 ## Merge requests
 
 **Create your first merge request**
@@ -25,8 +21,6 @@ comments: false
 1. Push a new commit to the same branch
 1. Review the changes again and notice the update
 
-----------
-
 ## Feedback and Collaboration
 
 - Merge requests are a time for feedback and collaboration
@@ -36,8 +30,6 @@ comments: false
 - Be as receptive as possible
 - Feedback is about the best code, not the person. You are not your code
 
-----------
-
 ## Feedback and Collaboration
 
 Review the Thoughtbot code-review guide for suggestions to follow when reviewing merge requests:

doc/university/training/topics/rollback_commits.md

@@ -4,40 +4,34 @@ comments: false
 
 # Rollback Commits
 
-----------
-
 ## Undo Commits
 
 - Undo last commit putting everything back into the staging area:
 
-    ```
+    ```sh
     git reset --soft HEAD^
     ```
 
 - Add files and change message with:
 
-    ```
+    ```sh
     git commit --amend -m "New Message"
     ```
 
-----------
-
 - Undo last and remove changes:
 
-    ```
+    ```sh
     git reset --hard HEAD^
     ```
 
 - Same as last one but for two commits back:
 
-    ```
+    ```sh
     git reset --hard HEAD^^
     ```
 
 ** Don't reset after pushing **
 
-----------
-
 ## Reset Workflow
 
 1. Edit file again 'edit_this_file.rb'
@@ -51,11 +45,9 @@ comments: false
 1. Pull for updates
 1. Push changes
 
-----------
-
 ## Commands
 
-```
+```sh
 # Change file edit_this_file.rb
 git status
 git commit -am "kjkfjkg"
@@ -68,15 +60,13 @@ git pull origin master
 git push origin master
 ```
 
-----------
-
 ## Note
 
 - git revert vs git reset
 - Reset removes the commit while revert removes the changes but leaves the commit
 - Revert is safer considering we can revert a revert
 
-```
+```sh
 # Changed file
 git commit -am "bug introduced"
 git revert HEAD

doc/university/training/topics/stash.md

@@ -4,14 +4,12 @@ comments: false
 
 # Git Stash
 
-----------
-
 We use git stash to store our changes when they are not ready to be committed
 and we need to change to a different branch.
 
 - Stash:
 
-    ```
+    ```sh
     git stash save
     # or
     git stash
@@ -21,18 +19,16 @@ and we need to change to a different branch.
 
 - Apply stash to keep working on it:
 
-    ```
+    ```sh
     git stash apply
     # or apply a specific one from out stack
     git stash apply stash@{3}
     ```
 
-----------
-
 - Every time we save a stash it gets stacked so by using list we can see all our
   stashes.
 
-    ```
+    ```sh
     git stash list
     # or for more information (log methods)
     git stash list --stat
@@ -40,7 +36,7 @@ and we need to change to a different branch.
 
 - To clean our stack we need to manually remove them:
 
-    ```
+    ```sh
     # drop top stash
     git stash drop
     # or
@@ -49,19 +45,15 @@ and we need to change to a different branch.
     git stash clear
     ```
 
-----------
-
 - Apply and drop on one command:
 
-    ```
+    ```sh
       git stash pop
     ```
 
 - If we meet conflicts we need to either reset or commit our changes.
 - Conflicts through `pop` will not drop a stash afterwards.
 
-----------
-
 ## Git Stash
 
 1. Modify a file
@@ -72,11 +64,9 @@ and we need to change to a different branch.
 1. Apply with pop
 1. View list to confirm changes
 
-----------
-
 ## Commands
 
-```
+```sh
 # Modify edit_this_file.rb file
 git add .
 

doc/university/training/topics/subtree.md

@@ -9,19 +9,15 @@ comments: false
 - For these cases we need a dependency control system.
 - Command are painfully long so aliases are necessary.
 
-----------
-
 ## Subtree Aliases
 
-- Add: git subtree add --prefix <target-folder> <url> <branch> --squash.
-- Pull: git subtree add --prefix <target-folder> <url> <branch> --squash.
-- Push: git subtree add --prefix <target-folder> <url> <branch>.
-- Ex: git config alias.sbp 'subtree pull --prefix st /
-  git@gitlab.com:balameb/subtree-nested-example.git master --squash'.
-
-----------
+- Add: `git subtree add --prefix <target-folder> <url> <branch> --squash`.
+- Pull: `git subtree add --prefix <target-folder> <url> <branch> --squash`.
+- Push: `git subtree add --prefix <target-folder> <url> <branch>`.
+- Ex: `git config alias.sbp 'subtree pull --prefix st /
+  git@gitlab.com:balameb/subtree-nested-example.git master --squash'`.
 
-```
+```sh
   # Add an alias
   # Add
   git config alias.sba 'subtree add --prefix st /
@@ -41,9 +37,7 @@ comments: false
 
 ```
 
-----------
-
-```
+```sh
   # Adding, or committing won't change the sub repo at remote
   # even if we push
   git add -A

doc/university/training/topics/tags.md

 ---
 comments: false
+type: reference
 ---
 
 # Tags
 
-----------
-
 - Useful for marking deployments and releases
 - Annotated tags are an unchangeable part of Git history
 - Soft/lightweight tags can be set and removed at will
 - Many projects combine an annotated release tag with a stable branch
 - Consider setting deployment/release tags automatically
 
-----------
-
 # Tags
 
 - Create a lightweight tag
@@ -24,11 +21,9 @@ comments: false
 
 <https://git-scm.com/book/en/Git-Basics-Tagging>
 
-----------
-
 # Commands
 
-```
+```sh
 git checkout master
 
 # Lightweight tag
@@ -40,3 +35,15 @@ git tag
 
 git push origin --tags
 ```
+
+<!-- ## Troubleshooting
+
+Include any troubleshooting steps that you can foresee. If you know beforehand what issues
+one might have when setting this up, or when something is changed, or on upgrading, it's
+important to describe those, too. Think of things that may go wrong and include them here.
+This is important to minimize requests for support, and to avoid doc comments with
+questions that you know someone might ask.
+
+Each scenario can be a third-level heading, e.g. `### Getting error message X`.
+If you have none to add when creating a doc, leave this section in place
+but commented out to help encourage others to add to it in the future. -->

doc/university/training/topics/unstage.md

@@ -4,8 +4,6 @@ comments: false
 
 # Unstage
 
-----------
-
 ## Unstage
 
 - To remove files from stage use reset HEAD where HEAD is the last commit of the current branch. This will unstage the file but maintain the modifications. 
@@ -20,17 +18,15 @@ comments: false
     git checkout -- <file>
     ```
 
-----------
-
 - To remove a file from disk and repo use 'git rm' and to rm a dir use the '-r' flag:
 
-    ```
+    ```sh
     git rm '*.txt'
     git rm -r <dirname>
     ```
 
 - If we want to remove a file from the repository but keep it on disk, say we forgot to add it to our `.gitignore` file then use `--cache`:
 
-    ```
+    ```sh
     git rm <filename> --cache
     ```

doc/university/training/user_training.md

 ---
 comments: false
+type: reference
 ---
 
 # GitLab Git Workshop
 
----
-
 ## Agenda
 
 1. Brief history of Git.
@@ -13,8 +12,6 @@ comments: false
 1. Configure your environment.
 1. Workshop.
 
----
-
 ## Git introduction
 
 <https://git-scm.com/about>
@@ -26,8 +23,6 @@ comments: false
 - Adapts to nearly any workflow.
 - Fast, reliable and stable file format.
 
----
-
 ## Help!
 
 Use the tools at your disposal when you get stuck.
@@ -36,14 +31,10 @@ Use the tools at your disposal when you get stuck.
 - Use Google.
 - Read documentation at <https://git-scm.com>.
 
----
-
 ## GitLab Walkthrough
 
 ![fit](logo.png)
 
----
-
 ## Configure your environment
 
 - Windows: Install 'Git for Windows'
@@ -56,8 +47,6 @@ Use the tools at your disposal when you get stuck.
 
 - Debian: '`sudo apt-get install git-all`' or Red Hat '`sudo yum install git-all`'
 
----
-
 ## Git Workshop
 
 ### Overview
@@ -70,8 +59,6 @@ Use the tools at your disposal when you get stuck.
 1. Merge requests.
 1. Feedback and Collaboration.
 
----
-
 ## Configure Git
 
 One-time configuration of the Git client:
@@ -81,8 +68,6 @@ git config --global user.name "Your Name"
 git config --global user.email you@example.com
 ```
 
----
-
 ## Configure SSH Key
 
 ```sh
@@ -111,8 +96,6 @@ cat ~/.ssh/id_rsa.pub
 ssh-rsa AAAAB3NzaC1yc2EAAAADAQEL17Ufacg8cDhlQMS5NhV8z3GHZdhCrZbl4gz you@example.com
 ```
 
----
-
 ## Create a project
 
 - Create a project in your user namespace.
@@ -120,8 +103,6 @@ ssh-rsa AAAAB3NzaC1yc2EAAAADAQEL17Ufacg8cDhlQMS5NhV8z3GHZdhCrZbl4gz you@example.
 - Create a '`development`' or '`workspace`' directory in your home directory.
 - Clone the '`training-examples`' project.
 
----
-
 ## Commands (project)
 
 ```sh
@@ -137,8 +118,6 @@ git clone git@gitlab.example.com:<username>/training-examples.git
 cd training-examples
 ```
 
----
-
 ## Git concepts
 
 ### Untracked files
@@ -153,8 +132,6 @@ Files that have been modified but are not committed.
 
 Modified files that have been marked to go in the next commit.
 
----
-
 ## Committing
 
 1. Edit '`edit_this_file.rb`' in '`training-examples`'.
@@ -165,8 +142,6 @@ Modified files that have been marked to go in the next commit.
 1. Push the commit to the remote.
 1. View the git log.
 
----
-
 ## Commands (committing)
 
 ```sh
@@ -179,8 +154,6 @@ git push origin master
 git log
 ```
 
----
-
 ## Feature branching
 
 - Efficient parallel workflow for teams.
@@ -190,8 +163,6 @@ git log
 - Push branches to the server frequently.
   - Hint: This is a cheap backup for your work-in-progress code.
 
----
-
 ## Feature branching steps
 
 1. Create a new feature branch called 'squash_some_bugs'.
@@ -199,8 +170,6 @@ git log
 1. Commit.
 1. Push.
 
----
-
 ## Commands (feature branching)
 
 ```sh
@@ -212,8 +181,6 @@ git commit -m 'Fix some buggy code'
 git push origin squash_some_bugs
 ```
 
----
-
 ## Merge requests
 
 - When you want feedback create a merge request.
@@ -224,8 +191,6 @@ git push origin squash_some_bugs
 - Anyone can comment, not just the assignee.
 - Push corrections to the same branch.
 
----
-
 ## Merge requests steps
 
 Create your first merge request:
@@ -235,8 +200,6 @@ Create your first merge request:
 1. Push a new commit to the same branch.
 1. Review the changes again and notice the update.
 
----
-
 ## Feedback and Collaboration
 
 - Merge requests are a time for feedback and collaboration.
@@ -246,8 +209,6 @@ Create your first merge request:
 - Be as receptive as possible.
 - Feedback is about the best code, not the person. You are not your code.
 
----
-
 ## Feedback and Collaboration resources
 
 Review the Thoughtbot code-review guide for suggestions to follow when reviewing merge requests:
@@ -255,8 +216,6 @@ Review the Thoughtbot code-review guide for suggestions to follow when reviewing
 
 See GitLab merge requests for examples: <https://gitlab.com/gitlab-org/gitlab-ce/merge_requests>.
 
----
-
 ## Explore GitLab projects
 
 ![fit](logo.png)
@@ -269,8 +228,6 @@ See GitLab merge requests for examples: <https://gitlab.com/gitlab-org/gitlab-ce
 - Manage project members
 - Project settings
 
----
-
 ## Tags
 
 - Useful for marking deployments and releases.
@@ -279,8 +236,6 @@ See GitLab merge requests for examples: <https://gitlab.com/gitlab-org/gitlab-ce
 - Many projects combine an annotated release tag with a stable branch.
 - Consider setting deployment/release tags automatically.
 
----
-
 ## Tags steps
 
 1. Create a lightweight tag.
@@ -289,8 +244,6 @@ See GitLab merge requests for examples: <https://gitlab.com/gitlab-org/gitlab-ce
 
 Additional resources: <http://git-scm.com/book/en/Git-Basics-Tagging>.
 
----
-
 ## Commands (tags)
 
 ```sh
@@ -306,8 +259,6 @@ git tag
 git push origin --tags
 ```
 
----
-
 ## Merge conflicts
 
 - Happen often.
@@ -315,8 +266,6 @@ git push origin --tags
 - Practice makes perfect.
 - Force push after fixing conflicts. Be careful!
 
----
-
 ## Merge conflicts steps
 
 1. Checkout a new branch and edit `conflicts.rb`. Add 'Line4' and 'Line5'.
@@ -325,8 +274,6 @@ git push origin --tags
 1. Commit and push to master.
 1. Create a merge request.
 
----
-
 ## Merge conflicts commands
 
 After creating a merge request you should notice that conflicts exist. Resolve
@@ -343,8 +290,6 @@ git rebase --continue
 git push origin <branch> -f
 ```
 
----
-
 ## Rebase with squash
 
 You may end up with a commit log that looks like this:
@@ -361,8 +306,6 @@ Does this work?
 
 Squash these in to meaningful commits using an interactive rebase.
 
----
-
 ## Rebase with squash commands
 
 Squash the commits on the same branch we used for the merge conflicts step.
@@ -373,8 +316,6 @@ git rebase -i master
 
 In the editor, leave the first commit as 'pick' and set others to 'fixup'.
 
----
-
 ## Questions?
 
 ![fit](logo.png)
@@ -383,9 +324,16 @@ Thank you for your hard work!
 
 ## Additional Resources
 
-- GitLab Documentation: <http://docs.gitlab.com/>.
-- GUI Clients: <http://git-scm.com/downloads/guis>.
-- Pro Git book: <http://git-scm.com/book>.
-- Platzi Course: <https://courses.platzi.com/courses/git-gitlab/>.
-- Code School tutorial: <http://try.github.io/>.
-- Contact us at `subscribers@gitlab.com`.
+See [additional resources](index.md#additional-resources).
+
+<!-- ## Troubleshooting
+
+Include any troubleshooting steps that you can foresee. If you know beforehand what issues
+one might have when setting this up, or when something is changed, or on upgrading, it's
+important to describe those, too. Think of things that may go wrong and include them here.
+This is important to minimize requests for support, and to avoid doc comments with
+questions that you know someone might ask.
+
+Each scenario can be a third-level heading, e.g. `### Getting error message X`.
+If you have none to add when creating a doc, leave this section in place
+but commented out to help encourage others to add to it in the future. -->