promote tutorials

Author: gilesknap

README.rst

@@ -11,18 +11,6 @@ Docs Source    https://github.com/epics-containers/k8s-epics-docs
 Documentation  https://epics-containers.github.io/k8s-epics-docs/
 ============== ==============================================================
 
-An important principal of the approach presented here is that an IOC container
-image represents a 'generic' IOC. The generic IOC image is used for all
-IOC instances that connect to a given class of device.
-
-An IOC instance runs in a container that bases its
-filesystem on a generic IOC image.
-In addition the instance has configuration mapped into the
-container that will bootstrap the unique properties of that instance.
-In most cases the configuration need only be a single IOC boot script.
-
-This approach reduces the number of images required and saves disk. It also
-makes for simple configuration management.
 
 .. |docs_ci| image:: https://github.com/epics-containers/k8s-epics-docs/workflows/Docs%20CI/badge.svg?branch=main
     :target: https://github.com/epics-containers/k8s-epics-docs/actions?query=workflow%3A%22Docs+CI%22

docs/explanations/whats_in.rst

@@ -61,6 +61,15 @@ Naming Convention for Repositories
 
 The following naming conventions help identify the source repositories. Note
 that where a repository generates an image the image will have the same name.
+e.g.
+
+- the repo
+
+  - https://github.com/epics-containers/epics-base
+- generates the image
+
+  - https://github.com/epics-containers/epics-base/pkgs/container/epics-base
+
 
 :epics:
     this prefix is for images that are nodes in the network of

docs/index.rst

@@ -6,17 +6,17 @@ How the documentation is structured
 
 .. rst-class:: columns
 
-:ref:`explanations`
-~~~~~~~~~~~~~~~~~~~
+:ref:`tutorials`
+~~~~~~~~~~~~~~~~
 
-Explanation of the principal ideas for deploying IOCs in Kubernetes.
+Tutorials for setting up a test cluster, and deploying an IOC.
 
 .. rst-class:: columns
 
-:ref:`tutorials`
-~~~~~~~~~~~~~~~~
+:ref:`explanations`
+~~~~~~~~~~~~~~~~~~~
 
-Tutorials for setting up a test cluster, and deploying an IOC.
+Explanation of the principal ideas for deploying IOCs in Kubernetes.
 
 .. rst-class:: columns
 
@@ -39,15 +39,6 @@ About the documentation
 
 `Why is the documentation structured this way? <https://documentation.divio.com>`_
 
-.. toctree::
-    :caption: Explanations
-    :name: explanations
-    :maxdepth: 1
-
-    explanations/whats_in
-    explanations/strategy
-    explanations/net_protocols
-
 .. toctree::
     :caption: Tutorials
     :name: tutorials
@@ -57,6 +48,15 @@ About the documentation
     tutorials/setup_k8s
     tutorials/manage_iocs
 
+.. toctree::
+    :caption: Explanations
+    :name: explanations
+    :maxdepth: 1
+
+    explanations/whats_in
+    explanations/strategy
+    explanations/net_protocols
+
 .. toctree::
     :caption: How-to Guides
     :name: how-to

docs/tutorials/introduction.rst

@@ -1,11 +1,47 @@
 Quick Start Introduction
 ========================
 
+Overview
+~~~~~~~~
+
+Kubernetes for EPICS IOCs provides the means to deploy and manage IOCs using
+modern industry standard approaches.
+
+This page briefly describes the technology and concepts behind this
+approach.
+
+Generic IOCs and instances
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+An important principal of the approach presented here is that an IOC container
+image represents a 'generic' IOC. The generic IOC image is used for all
+IOC instances that connect to a given class of device.
+
+An IOC instance runs in a container that bases its
+filesystem on a generic IOC image.
+In addition the instance has configuration mapped into the
+container that will bootstrap the unique properties of that instance.
+In most cases the configuration need only be a single IOC boot script.
+
+This approach reduces the number of images required and saves disk. It also
+makes for simple configuration management.
+
+Throughout this documentation we will use the terms Generic IOC and
+IOC Instance. The word IOC without this context is ambiguous.
+
+Images and Containers
+~~~~~~~~~~~~~~~~~~~~~
+**TODO**
+
+Kubernetes
+~~~~~~~~~~
+**TODO**
+
+Helm
+~~~~
+**TODO**
+
+Ibek
+~~~~
 **TODO**
 
-will briefly describe
-  - generic iocs and ioc instances
-  - kubernetes
-  - kubectl
-  - helm
-  - ibek