Enterprise workspaces description (#3354)

* Create workspaces-eom.md

initial version

* workspaces settings picture

* Update workspaces-eom.md

added config info

* Update workspaces-eom.md

formattign and further reading references

* Update enterprise_sidebar.html

adding workspaces & cache to enterprise sidebar

* Update using-workspaces.md

added additional exampel of using multiple workspaces

* Update sidebar.html with roskpaces reference

Author: michal-at-travisci

_includes/enterprise_sidebar.html

@@ -63,6 +63,7 @@ <h3>Enterprise Operations Manual</h3>
         <li><a href="/user/enterprise/troubleshooting-guide/">Troubleshooting Guide</a></li>
         <li><a href="/user/enterprise/user-management/">User Management</a></li>
         <li><a href="/user/enterprise/Multi-CPU-Builds/">Multi CPU builds</a></li>
+        <li><a href="/user/enterprise/workspaces-eom/">Workspaces & Cache</a></li>
       </ul>
 
       <h3>Migrating from Enterprise 2.x to 3.x</h3>

_includes/sidebar.html

@@ -59,6 +59,7 @@ <h3>Installing Dependencies</h3>
         <li><a href="/user/private-dependencies-bb/">Private Dependencies Bitbucket</a></li>
         <li><a href="/user/database-setup/">Setting up Services and Databases</a></li>
         <li><a href="/user/caching/">Caching Dependencies</a></li>
+        <li><a href="/user/using-workspaces/">Caching Dependencies within a Build (Workspaces)</a></li>
         <li><a href="/user/ssh-known-hosts/">Adding to SSH Known Hosts</a></li>
       </ul>
 

images/tcie-3.x-workspaces-config.png

@@ -0,0 +1,41 @@
+---
+title: Enterprise Workspaces & Cache
+layout: en_enterprise
+
+---
+
+This page contains operations manual level information about Workspaces and Cache in Trravis CI Enterprise.
+
+## Cache vs Workspaces
+
+Cache, aka Build Cache, is configured file bucket which serves a purpose as a cache for build artifacts. Users of Travis CI enterprise may put or pull to/from the Cache the build artifacts.
+**Cache is meant for utilizing items between builds**.
+
+Workspaces, aka Build Workspaces, is a kind of cache, but with specific goal in mind: serves a purpose to share artifacts/files between **jobs within the same build**. The main use case is 
+when a binary or library (or other dependency) requires rebuilding before any other build job within build may progress. Workspaces are introduced in Travis CI Enterprise after [version 3.0.53](https://enterprise-changelog.travis-ci.com/release-3-0-53-283095).
+
+Both features are technically specifically configured file buckets.
+
+### Workspaces configuration
+
+Workspaces are configured much like Cache - in the Travis CI Enterprsie platform admin application. The configuration is technically propagated to travis-build service during runtime.
+
+There's a new menu called "Workspaces UI Settings", where specific configuration items must be provided in order to enable feature for the end users.
+
+![TCIE Workspaces Settings](/images/tcie-3.x-workspaces-config.png)
+
+> *Please note:*
+> 
+> Workspaces are meant for short-lived artifacts.
+>
+> It is recommended to:
+> 
+> * use separate file bucket than the one used for cache, both for security and maintenance reasons
+> * have a file bucket configured with auto-cleanup policy (TCIE is not performing any housekeeping on the file bucket) - default recommended is 3 hours (maximum default time of a single job running uninterrupted under certain allowance configurations)
+> * make sure your infrastructure hosting build image instances has connectivity to the file bucket configured for workspaces
+
+### Workspaces usage
+
+Please see [our documentation](/user/using-workspaces) for end-user facing usage instructions for Workspaces.
+
+Please read also [about build stages](/user/build-stages/) in order to create streamlined set of jobs, which can be used e.g. for pre-building a short lived artifact in first steps of build pipeline. 

user/enterprise/workspaces-eom.md

@@ -3,11 +3,7 @@ title: Using Workspaces (Beta)
 layout: en
 ---
 
-# Workspaces (Beta)
-
-> Workspaces are currently in beta testing, and may change without a prior
-> notice.
-{: .beta}
+# Workspaces
 
 Workspaces allow jobs _within_ a build to share files.
 They are useful when you want to use build artifacts from a previous job;
@@ -94,6 +90,72 @@ In this example:
      produced by the jobs in the previous stage, and deploy it
      using a custom script.
 
+A more explicit example below:
+
+
+```
+jobs:
+  include:
+    - stage: Build and Test
+      name: "Job A"
+      script:
+        - echo "Building Job A"
+        - echo "Running tests for Job A"
+        - mkdir -p workspace-a
+        - echo "This is data from Job A" > workspace-a/data-A.txt
+      workspaces:
+        create:
+          name: workspace-a
+          paths:
+            - workspace-a
+
+    - name: "Job B"
+      script:
+        - echo "Building Job B"
+        - echo "Running tests for Job B"
+        - mkdir -p workspace-b
+        - echo "This is data from Job B" > workspace-b/data-B.txt
+      workspaces:
+        create:
+          name: workspace-b
+          paths:
+            - workspace-b
+
+    - name: "Job C"
+      script:
+        - echo "Building Job C"
+        - echo "Running tests for Job C"
+        - mkdir -p workspace-c
+        - echo "This is data from Job C" > workspace-c/data-C.txt
+      workspaces:
+        create:
+          name: workspace-c
+          paths:
+            - workspace-c
+
+    - stage: Deploy
+      name: "Deploy"
+      script:
+        - echo "Deploying using artifacts from Job A Job B and Job C"
+        - cat workspace-a/data-A.txt
+        - cat workspace-b/data-B.txt
+        - cat workspace-c/data-C.txt
+      workspaces:
+        use:
+          - workspace-a
+          - workspace-b
+          - workspace-c
+```
+{: data-file=".travis.yml"}
+
+In above example:
+
+1. Build stage "Build and Test" consists of 3 jobs, each of them producing output to a separate workspace
+2. Build stage "Deploy" consists of one job, which
+    1. Marks usage of all 3 previosuly created workspaces
+    2. pulls data out of each previously created workspace and echoes it to standard output to demonstrate ability to access workspace
+
+
 ## Workspaces and concurrency
 Note that workspaces work best if there is no race condition set while
 uploading them.