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

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