tweaks to devcontainer explanations

Author: gilesknap

docs/user/tutorials/devcontainer.rst

@@ -1,11 +1,15 @@
 
-Setup the Devcontainer
-======================
+Setup a Devcontainer
+====================
 
 Introduction
 ------------
 
 The devcontainer provides the environment in which you will do all your development.
+This is a basic tutorial that introduces the concept in preparation for the
+epics devcontainer tutorial.
+
+.. seealso:: `epics_devcontainer`
 
 
 Configure Visual Studio Code
@@ -37,22 +41,16 @@ settings editor and search for
 Launching the Devcontainer
 --------------------------
 
-To setup your devcontainer, perform the following steps:
-
--  create a workspace folder
--  clone the .devcontainer repository into the workspace folder
--  open the workspace folder with Visual Studio Code.
-
-for example:
+If your repository contains a ``.devcontainer`` directory, vscode will be
+able to follow the instructions inside and launch a container.
 
 .. code-block:: bash
 
-    mkdir work-ec
-    cd work-ec
-    git clone [email protected]:epics-containers/.devcontainer.git
+    git clone <repo>
+    cd <repo>
     code .
 
-This will open the workspace folder in Visual Studio Code. You will be prompted
+This will open the project folder in Visual Studio Code. You will be prompted
 to reopen the folder in a container. Click on the ``Reopen in Container`` button.
 
 .. figure:: ../images/vscode-reopen-in-container.png

docs/user/tutorials/epics_devcontainer.rst

@@ -5,18 +5,36 @@ The EPICS Devcontainer
 Introduction
 ------------
 
-You can setup a single devcontainer for managing all of your IOCs.
+You can setup a single devcontainer for managing all of your IOCs. In
+`devcontainer` we launched a devcontainer for a single project. Here we
+will create a workspace that is managed by a devcontainer. This will allow
+you to manage multiple projects in a single devcontainer.
 
 The base container is defined in https://github.com/epics-containers/dev-e7
 but we will use a customizable image derived from that. The customizable
 container definition is in https://github.com/epics-containers/.devcontainer.
 
-.. seealso:: Basic devcontainer setup: `./devcontainer`
-
 
 Launching the Devcontainer
 --------------------------
 
+To setup your devcontainer, perform the following steps:
+
+-  create a workspace folder
+-  clone the .devcontainer repository into the workspace folder
+-  open the workspace folder with Visual Studio Code.
+
+for example:
+
+.. code-block:: bash
+
+    mkdir work-ec
+    cd work-ec
+    git clone [email protected]:epics-containers/.devcontainer.git
+    code .
+
+.. seealso:: `./devcontainer`
+
 Having setup your devcontainer, to verify things are working as expected,
 open a terminal in VSCode from the menus ``Terminal > New Terminal``.
 You should see a prompt like this:
@@ -46,6 +64,10 @@ Things to note:
   written with your user id and group id when writing to the mounted
   workspace folder (or your home directory).
 
+- In the following tutorials we will create further project folders and add
+  them to the workspace that you have just created. These projects will
+  all be managed inside the devcontainer we have just set up.
+
 .. _devcontainer-configure:
 
 Configuring the Devcontainer