Expand documentation for STEWARDS

doc/resource.texinfo

@@ -4,18 +4,20 @@
 
 @subsection Introduction to Resources
 
-Resources are responsible for resources examined and consumed by the
-deployment of software components.
-
-Some examples of resources and resources they are responsible for are
-the localhost and users, files, and software packages; a configured
-docker engine and docker volumes, images and deployments; a remote
-host accessible over SSH and users, files, and software packages; a
-kubernetes cluster hosted in a public cloud and the rich landscape of
-resources it can manage.
-
-Resources are persistent objects that are attached to a tenant and a
-project.
+Resources represent handles for the underlying resources resources
+examined, created, deleted and consumed during the deployment and
+operation of infrastructure stacks. The actual resource represented by
+an instance of the class @code{resource} is referred to as the
+@i{underlying resource} while the instance is reffered to as the
+@i{resource handle} when the distinction must be empahsised.
+
+Resource handles are persistent objects that are attached to a tenant
+and a project.
+
+@subsection Resource Steward
+
+Every resource is attached to a steward which is responsible for
+modifying or examining the underlying resource.
 
 @section The Resources Dictionary
 

doc/steward.texinfo

@@ -4,19 +4,33 @@
 
 @subsection Introduction to Stewards
 
-Stewards are responsible for resources examined and consumed by the
-deployment of software components.
+Stewards are responsible for resources examined, created, deleted and
+consumed during the deployment and operation of infrastructure stacks.
 
 Some examples of stewards and resources they are responsible for are
-the localhost and users, files, and software packages; a configured
-docker engine and docker volumes, images and deployments; a remote
-host accessible over SSH and users, files, and software packages; a
-kubernetes cluster hosted in a public cloud and the rich landscape of
-resources it can manage.
+the UNIX localhost and its users, files, and software packages; a
+configured docker engine and its docker volumes, images and
+deployments; a remote UNIX host accessible over SSH and its users,
+files, and software packages; a kubernetes cluster hosted in a public
+cloud and the rich landscape of resources it can manage.
 
 Stewards are persistent objects that are attached to a tenant and a
 project.
 
+@subsection Steward Configuration
+
+Before a steward can operate it may require a preparation step that we
+call @i{configuration}.  This step must prepare transient resources
+that a steward requires to operate, it must also perform appropriate
+verifications to prevent operational errors.
+
+For instance a steward responsible for creating files in a specific
+directory of the local file system could verify that this directory
+exists and that the program has appropriate rights to create files in
+this directory.  A steward interacting with a web service could verify
+the connectivity to the web service, the availability and validity of
+credentials for that service.
+
 @section The Stewards Dictionary
 
 @include include/class-org.melusina.cid-steward.texinfo

src/steward.lisp

@@ -18,24 +18,23 @@
     :type tenant
     :reader tenant
     :initarg :tenant
-    :initform *tenant*)
+    :initform *tenant*
+    :documentation "The TENANT this STEWARD operates for.")
    (project
     :type project
     :reader project
     :initarg :project
-    :initform *project*)
+    :initform *project*
+    :documentation "The PROJECT this STEWARD operates for.")
    (description
     :type (or string null)
     :initarg :description
     :reader description
     :initform nil
     :documentation "A short description of the STEWARD."))
-  (:documentation "The class represents stewards responsible for
-resources consumed by the deployment of software components.
-
-Some examples of STEWARDS are the localhost, a configured docker engine,
-a remote host accesible over SSH, a kubernetes cluster hosted in
-a public cloud, among many other possibilities."))
+  (:documentation "The class represents stewards responsible for resources
+that are examined, created, deleted and consumed during the deployment
+of infrastructure stacks."))
 
 (defmethod initialize-instance :after ((instance steward) &rest initargs &key &allow-other-keys)
   (declare (ignore initargs))