From ca7eef520434983ed4926fd7db06b97075627298 Mon Sep 17 00:00:00 2001
From: OlgaGusarenko <ogusarenko@mirantis.com>
Date: Fri, 4 Sep 2015 16:08:56 +0300
Subject: [PATCH] [Contributor Guide] Documentation structure

Converts the Documentation structure wikipage
https://wiki.openstack.org/wiki/Documentation/Structure
to RST.

PS: the RST include file policy section will be addressed in the
RST-related section

Change-Id: Id070fc447a17efd364a741223b1c60dfcb2ad1df
Implements: blueprint docs-contributor-guide
---
 .../source/docs-structure.rst                 | 106 ++++++++++++++++++
 doc/contributor-guide/source/index.rst        |   3 +-
 .../source/{rst_conv.rst => rst-conv.rst}     |   0
 3 files changed, 108 insertions(+), 1 deletion(-)
 create mode 100644 doc/contributor-guide/source/docs-structure.rst
 rename doc/contributor-guide/source/{rst_conv.rst => rst-conv.rst} (100%)

diff --git a/doc/contributor-guide/source/docs-structure.rst b/doc/contributor-guide/source/docs-structure.rst
new file mode 100644
index 0000000000..50d97721a5
--- /dev/null
+++ b/doc/contributor-guide/source/docs-structure.rst
@@ -0,0 +1,106 @@
+
+.. _docs-structure:
+
+=======================
+Documentation structure
+=======================
+
+.. _filename-conv:
+
+File naming conventions
+~~~~~~~~~~~~~~~~~~~~~~~
+
+For XML filenames, to indicate the hierarchical type of files use
+the following prefixes:
+
+* ``bk_`` for book,
+* ``ch_`` for chapter,
+* ``section_`` for section
+* ``app_`` for appendix.
+
+For RST filenames:
+
+* follow page-based, topical approach to file naming and do not apply
+  any special prefixes,
+
+* use hyphen as a space delimiter.
+
+When migrating XML to RST, use the ``xml:id`` attribute value from a source
+file as a filename for a converted file. For example, if the source XML file
+contains ``xml:id="technical_considerations_multi_site"``, name the newly
+created RST file as follows::
+
+  technical-considerations-multi-site.rst
+
+
+Directory structure
+~~~~~~~~~~~~~~~~~~~
+
+For better organization, use subdirectories to organize the files
+by a particular grouping such as project or topic.
+
+Common practices include:
+
+* Figure subdirectory includes images (both PNG and SVG source files).
+* Sample subdirectory contains samples of source code and configuration files.
+* Chapter subdirectory stores all sections included in one chapter with the
+  parent file located in the top level directory.
+
+
+Structure checklist
+~~~~~~~~~~~~~~~~~~~
+
+Use the following checklist for a DocBook manual.
+
+.. list-table:: **DocBook manual checklist**
+   :widths: 10 30 5
+   :header-rows: 1
+
+   * - Task
+     - Make sure that
+     - Tick if done
+
+   * - :file:`pom.xml` file
+     - Your `pom.xml` file uses the latest (non-SNAPSHOT) cloud-doc plugin
+       version and is configured correctly. To find the version number
+       of the latest plugin, go to `Clouddocs Maven Plugin Release Notes`_.
+     -
+
+   * - TOC
+     - Your :file:`pom.xml` file configures a TOC for your book.
+     -
+
+   * - Glossary
+     - You embedded the shared glossary and marked terms with
+       the ``<glossterm>`` tag in your document.
+     -
+
+   * - Preface
+     - Your book has a preface.
+     -
+
+   * - Document history
+     - The preface includes the document history. Also make sure that you have
+       included a revision entry for your latest change.
+     -
+
+   * - Titles
+     - Titles correspond to the file content
+     -
+
+   * - Code samples
+     - Code samples are in separate files and included in chapter,
+       section, or appendix file.
+     -
+
+   * - Chunking
+     - Chapters and appendices are in separate files and included in the book file.
+     -
+
+   * - Source filenames
+     - Source filenames use :ref:`filename-conv`.
+     -
+
+
+.. _`Clouddocs Maven Plugin Release Notes`: https://github.com/rackerlabs/clouddocs-maven-plugin#release-notes
+
diff --git a/doc/contributor-guide/source/index.rst b/doc/contributor-guide/source/index.rst
index 9f938e6c20..b2a37e840a 100644
--- a/doc/contributor-guide/source/index.rst
+++ b/doc/contributor-guide/source/index.rst
@@ -16,7 +16,8 @@ Contents
    :maxdepth: 2
 
    introduction.rst
-   rst_conv.rst
+   rst-conv.rst
+   docs-structure.rst
 
 Search in this guide
 ~~~~~~~~~~~~~~~~~~~~
diff --git a/doc/contributor-guide/source/rst_conv.rst b/doc/contributor-guide/source/rst-conv.rst
similarity index 100%
rename from doc/contributor-guide/source/rst_conv.rst
rename to doc/contributor-guide/source/rst-conv.rst