1 files changed, 54 insertions, 0 deletions
diff --git a/doc/development/writing_specification.txt b/doc/development/writing_specification.txt
new file mode 100644
index 000000000..4e1c03483
--- /dev/null
+++ b/doc/development/writing_specification.txt
@@ -0,0 +1,54 @@
+.. -*- mode: rst -*-
+
+.. _development-writing_specification:
+
+===========================
+Writing Bcfg2 Specification
+===========================
+
+Bcfg2 specifications are logically divided in to three areas:
+
+* Metadata
+* Abstract
+* Literal
+
+The metadata portion of the configuration assigns a client to its profile
+group and to its non-profile groups. The profile group is assigned
+in ``Metadata/clients.xml`` and the non profile group assignments are in
+``Metadata/groups.xml``.
+
+The group memberships contained in the metadata are then used to constuct
+an abstract configuration for the client. An abstract configuration for
+a client identifies the configuration entities (packages, configuration
+files, service, etc) that a client requires, but it does not identify
+them explicitly. For instance an abstract configuration may identify
+that a client needs the Bcfg2 package with
+
+.. code-block:: xml
+
+    <Package name=bcfg2/>
+
+but this does not explicitly identify that an RPM package version
+0.9.2 should be loaded from http://rpm.repo.server/bcfg2-1.0.1-0.1.rpm.
+The abstract configuration is defined in the xml configuration files
+for the Base and Bundles plugins.
+
+A combination of a clients metadata (group memberships) and abstract
+configuration is then used to generate the clients literal configuration.
+For instance the above abstract configuration entry may generate a
+literal configuration of
+
+
+.. code-block:: xml
+
+    <Package name='bcfg2' version='1.0.1-0.1' type='yum'/>
+
+A clients literal configuration is generated by a number of plugins that
+handle the different configuration entities.
+
+
+.. figure:: specification_overview.png
+   :width:  60%
+   :alt:    Specification overview
+   :align:  center
+