Add instructions for how to use the specs project

Introduces guidelines for naming, movement, and indexing of specs
documents

Change-Id: I759ab242937f6816424770871dbf795d8aee06bd

README.rst

@@ -0,0 +1,18 @@
+..
+  This work is licensed under a Creative Commons Attribution 3.0 Unported
+  License.
+
+  http://creativecommons.org/licenses/by/3.0/legalcode
+
+.. airship-specs-readme:
+
+====================================
+Building Airship Specs Documentation
+====================================
+
+Using the equivalent of `pip install sphinx`, install the sphinx-build command
+if it is not already installed.
+
+From the root of this project, issue the command `make html`.
+Sphinx will render the output into doc/build/html. Open
+doc/build/html/index.html using your browser.

doc/source/index.rst

@@ -6,8 +6,10 @@
 Airship Specs Documentation
 ===========================
 
-Proposed Specs
---------------
+:ref:`genindex`
+
+About Specs
+-----------
 
 .. toctree::
    :maxdepth: 1
@@ -32,4 +34,3 @@ Implemented Specs
    :glob:
 
    specs/implemented/*
-

specs/approved/_placeholder.rst

@@ -0,0 +1,8 @@
+.. placeholder:
+
+===========
+Placeholder
+===========
+
+This file is a placeholder and should be deleted when the first spec is moved
+to this directory.

specs/implemented/_placeholder.rst

@@ -0,0 +1,8 @@
+.. placeholder:
+
+===========
+Placeholder
+===========
+
+This file is a placeholder and should be deleted when the first spec is moved
+to this directory.

specs/instructions.rst

@@ -0,0 +1,96 @@
+..
+  This work is licensed under a Creative Commons Attribution 3.0 Unported
+  License.
+
+  http://creativecommons.org/licenses/by/3.0/legalcode
+
+.. index::
+   single: instructions
+   single: getting started
+
+.. _instructions:
+
+============
+Instructions
+============
+
+- Use the template.rst as the basis of your specification.
+- Attempt to detail each applicable section.
+- If a section does not apply, use N/A, and optionally provide
+  a short explanation.
+- New specs for review should be placed in the ``approved`` subfolder, where
+  they will undergo review and approval in Gerrit_.
+- Specs that have finished implementation should be moved to the
+  ``implemented`` subfolder
+
+Indexing and Categorization
+---------------------------
+
+Use of the `index`_ directive in reStructuredText for each document provides
+the ability to generate indexes to more easily find items later. Authors are
+encouraged to use index entries for their documents to help with discovery.
+
+Naming
+------
+
+Document naming standards help readers find specs. For the Airship repository,
+the following document naming is recommended. The categories listed here are
+likely incomplete, and may need expansion to cover new cases. It is preferrable
+to deviate (and hopefully amend the list) than force document names into
+nonsense categories. Prefer using categories that have previously been used or
+that are listed here over new categories, but don't force the category into
+something that doesn't make sense.
+
+Document names should follow a pattern as follows::
+
+  [category]_title.rst
+
+Use the following guidelines to determine the category to use for a document:
+
+1) For new functionality and features, the best choice for a category is to
+   match a functional duty of Airship.
+
+site-definition
+  Parts of the platform that support the definition of a site, including
+  management of the yaml definitions, document authoring and translation, and
+  the collation of source documents.
+
+genesis
+  Used for the steps related to preparation and deployment of the genesis node
+  of an Airship deployment.
+
+baremetal
+  Those changes to Airflow that provide for the lifecycle of bare metal
+  components of the system - provisioning, maintenance, and teardown. This
+  includes booting, hardware and network configuration, operating system, and
+  other host-level management
+
+k8s
+  For functionality that is about interfacing with Kubernetes directly, other
+  than the initial setup that is done during genesis.
+
+software
+  Functionality that is related to the deployment or redeployment of workload
+  onto the Kubernetes cluster.
+
+workflow
+  Changes to existing workflows to provide new functionality and creation of
+  new workflows that span multiple other areas (e.g. baremetal, k8s, software),
+  or those changes that are new arrangements of existing functionality in one
+  or more of those other areas.
+
+administration
+  Security, logging, auditing, monitoring, and those things related to site
+  administrative functions of the Airship platform.
+
+2) For specs that are not feature focused, the component of the system may
+   be the best choice for a category, e.g. ``shipyard``, ``armada`` etc...
+   When there are multiple components involved, or the concern is cross
+   cutting, use of ``airship`` is an acceptable category.
+
+3) If the spec is related to the ecosystem Airship is maintained within, an
+   appropriate category would be related to the aspect it is impacting, e.g.:
+   ``git``, ``docker``, ``zuul``, etc...
+
+.. _index: http://www.sphinx-doc.org/en/stable/markup/misc.html#directive-index
+.. _Gerrit: https://review.openstack.org/#/q/project:openstack/airship-specs

specs/template.rst

@@ -4,10 +4,20 @@
 
   http://creativecommons.org/licenses/by/3.0/legalcode
 
+.. index::
+   single: template
+   single: creating specs
+
 .. note::
 
   Blueprints are written using ReSTructured text.
 
+Add index directives to help others find your spec. E.g.::
+
+  .. index::
+     single: template
+     single: creating specs
+
 =====================================
 Template: The title of your blueprint
 =====================================