Merge "Add draft of diagram guidelines."

doc/contributor-guide/source/diagram-guidelines.rst

@@ -0,0 +1,24 @@
+.. _diagramguidelines:
+
+==================
+Diagram guidelines
+==================
+
+Diagram guidelines are
+intended for designers, developers, or reviewers
+contributing illustrations to OpenStack documentation.
+
+
+
+.. toctree::
+   :maxdepth: 2
+
+   diagram-guidelines/diagram-usage.rst
+   diagram-guidelines/tools.rst
+   diagram-guidelines/files.rst
+   diagram-guidelines/general-guidelines.rst
+
+In addition to these resources, ensure you
+review the :ref:`stg_writing_style` section. The general
+writing style guidelines also apply to content in
+diagrams.

doc/contributor-guide/source/diagram-guidelines/diagram-usage.rst

@@ -0,0 +1,36 @@
+.. _diagramusage:
+
+======================
+Use diagrams sparingly
+======================
+
+Diagrams can be useful tools to help orient users visualize complex
+processes. However, diagrams can sometimes be too simplistic, confusing
+the user instead of helping. The decision about whether a diagram is
+useful depends on the context of each project and the discretion
+of each contributor and reviewer.
+
+When to use diagrams
+~~~~~~~~~~~~~~~~~~~~
+
+Include diagrams in OpenStack documentation in the following
+situations:
+
+* If there is evidence of a process, whether the process is
+  is automated or manual
+
+  Example: Basic setup workflow
+
+* If you need to clarify configurations and reference architectures
+
+  Example: Code review, upstream versus local environment
+
+
+When not to use diagrams
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+Do not include diagrams in the following situations:
+
+* When a workflow is too simplistic
+* When there is no interaction with an OpenStack project
+* When a configuration can be easily explained through text

doc/contributor-guide/source/diagram-guidelines/files.rst

@@ -0,0 +1,41 @@
+.. _dg_files:
+
+============================
+Use recommended file formats
+============================
+
+Each diagram should include files in the following formats:
+
+* Raster, always Portable Network Graphics (``.png``).
+  The documentation build process uses these files.
+* Vector, typically Scalable Vector Graphics (``.svg``).
+  Most illustration tools support editing these files.
+* Original, typically the native format of the tool.
+
+At a minimum, each diagram must include a ``.png`` and ``.svg`` file.
+
+Furthermore, any outside stencils or objects added to a diagram
+should also be ``.svg`` files, so that reviewers can edit individual elements
+of the diagram.
+
+.. Note:: Using ``.svg`` files for individual elements may cause rendering
+   issues when editing the diagram in a different tool than the one
+   from which the diagram was originally created.
+
+File names
+~~~~~~~~~~
+
+Contributors must create unique and meaningful file names to
+differentiate between diagrams. An example of this is the name
+``cg-workflow-digram.png``. ``cg`` indicates that this diagram belongs
+in the contributor guidelines, the acronym created by taking
+the first letters of the OpenStack book name.  ``workflow-diagram.png``
+provides a description of what the diagram is about, as well as the
+file type extension.
+
+Other file guidelines
+~~~~~~~~~~~~~~~~~~~~~
+
+* Files must be saved with a transparent background.
+* Files must be saved in a landscape document style.
+* Diagram width and height should be no more than 900pt.

doc/contributor-guide/source/diagram-guidelines/general-guidelines.rst

@@ -0,0 +1,76 @@
+.. _dg_general:
+
+==================
+General guidelines
+==================
+
+Text format
+~~~~~~~~~~~
+
+* Set the font to Open Sans. If your tool does not have Open Sans, set
+  the font to a different sans serif font, like Helvetica.
+* Set the font size to at least 6px or above.
+* All objects must be labeled with text.
+
+
+Objects
+~~~~~~~
+
+* An object must be a closed geometric shape or icon.
+* Objects must have a hollow middle, where text can be added.
+* All objects must be labeled according to their function.
+
+
+Object color
+~~~~~~~~~~~~
+
+Any objects inside a diagram should be black, unless the object
+needs to be emphasized within a diagram in order to fully
+understand its function. Colored objects may only use
+bright primary colors, such as light blue, red, or green. You can make
+multiple objects the same color, provided the objects serve
+similar functions or purposes.
+
+
+Lines
+~~~~~
+
+* Set line width to at least 2px or above.
+* Avoid crossing an object with a line.
+
+The following are recommendations for line shape and usage.
+
+Line shape
+----------
+
+Keep lines straight unless a line needs to change direction. If
+a line changes direction to reach an object, the corner in
+which the change of direction occurs must be rounded.
+
+Solid lines
+-----------
+
+Use solid lines to show a direct relationship between objects.
+For example, objects within a reference architecture that are
+used in conjunction with each other.
+
+Dashed lines
+------------
+
+Use dashed lines to group objects connected through an online
+network. For example, an object that uses neutron to connect
+to a server.
+
+Dotted lines
+------------
+
+Use dotted lines to show how data entered by a human user travels.
+
+
+Arrows
+~~~~~~
+
+Use arrows to represent one-way interactions between two or more
+objects. If an object is attached to an arrow, it implies that the
+function represented by the object can only work when interacting
+with another object in the diagram.

doc/contributor-guide/source/diagram-guidelines/tools.rst

@@ -0,0 +1,27 @@
+.. _dg_tools:
+
+=====
+Tools
+=====
+
+There are many tools you can use to create a diagram,
+and contributors are free to use the tool of their choice.
+
+However, elements within a diagram must be easily edited or
+easy to reproduce with a different tool. Follow the file saving
+conventions outlined in :ref:`dg_files`.
+This ensures that a diagram can be reviewed and edited as OpenStack
+projects continue to change.
+
+Open source tools can help streamline the review process by making
+diagrams easy to edit. Many open-source tools contain shapes and
+stencils that can be used in OpenStack. The following is a list
+recommended open source tools:
+
+* `Draw.io <https://www.draw.io/>`_: Draw.io contains most of the
+  customization options needed to make diagrams. Diagrams can also
+  be saved as an ``.svg`` file, which allows contributors to edit
+  individual elements of each diagram.
+
+.. I have left this space for other contributors to recommend
+   any other open source diagram tools.

doc/contributor-guide/source/index.rst

@@ -27,6 +27,7 @@ Contents
    ui-text-guidelines.rst
    rst-conv.rst
    json-conv.rst
+   diagram-guidelines.rst
    docs-review.rst
    docs-builds.rst
    doc-tools.rst