4bad9aee97
Change-Id: Ibfb26b8c5fdd745c6748d32c60a62c38f1e0a7a4
1018 B
1018 B
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