From cb7c8d07afd70b6ad028d97549549f7cec795cb3 Mon Sep 17 00:00:00 2001 From: Nathaniel Archer Date: Tue, 19 Jul 2016 11:09:33 -0500 Subject: [PATCH] Add draft of diagram guidelines. Change-Id: I28dbdd0f545317b50809396d47dfbb462430b748 --- .../source/diagram-guidelines.rst | 24 ++++++ .../diagram-guidelines/diagram-usage.rst | 36 +++++++++ .../source/diagram-guidelines/files.rst | 41 ++++++++++ .../diagram-guidelines/general-guidelines.rst | 76 +++++++++++++++++++ .../source/diagram-guidelines/tools.rst | 27 +++++++ doc/contributor-guide/source/index.rst | 1 + 6 files changed, 205 insertions(+) create mode 100644 doc/contributor-guide/source/diagram-guidelines.rst create mode 100644 doc/contributor-guide/source/diagram-guidelines/diagram-usage.rst create mode 100644 doc/contributor-guide/source/diagram-guidelines/files.rst create mode 100644 doc/contributor-guide/source/diagram-guidelines/general-guidelines.rst create mode 100644 doc/contributor-guide/source/diagram-guidelines/tools.rst diff --git a/doc/contributor-guide/source/diagram-guidelines.rst b/doc/contributor-guide/source/diagram-guidelines.rst new file mode 100644 index 0000000000..e0fade4577 --- /dev/null +++ b/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. diff --git a/doc/contributor-guide/source/diagram-guidelines/diagram-usage.rst b/doc/contributor-guide/source/diagram-guidelines/diagram-usage.rst new file mode 100644 index 0000000000..b6db60097c --- /dev/null +++ b/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 diff --git a/doc/contributor-guide/source/diagram-guidelines/files.rst b/doc/contributor-guide/source/diagram-guidelines/files.rst new file mode 100644 index 0000000000..15a57131d9 --- /dev/null +++ b/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. diff --git a/doc/contributor-guide/source/diagram-guidelines/general-guidelines.rst b/doc/contributor-guide/source/diagram-guidelines/general-guidelines.rst new file mode 100644 index 0000000000..b9912cbe8d --- /dev/null +++ b/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. diff --git a/doc/contributor-guide/source/diagram-guidelines/tools.rst b/doc/contributor-guide/source/diagram-guidelines/tools.rst new file mode 100644 index 0000000000..5a2898ab44 --- /dev/null +++ b/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 `_: 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. diff --git a/doc/contributor-guide/source/index.rst b/doc/contributor-guide/source/index.rst index 05687acc8f..7ca7f724ea 100644 --- a/doc/contributor-guide/source/index.rst +++ b/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