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 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
