Diagram Guidelines
Warning
This page needs updated content and examples for MongoDB. Though incomplete, this page contains useful information and should be considered a resource though it is under revision.
Diagrams can help users visualize complex processes in a simplified way. Sometimes, diagrams can be too simplistic, confusing rather than helping the user. The decision about whether a diagram might be helpful depends on the context of each document and the discretion of each writer.
When to Use Diagrams
Include diagrams in the following situations:
When there is evidence of a process, whether the process is automated or manual
When you need to clarify configurations and settings, such as the architecture for virtual servers
When you need to define a complex workflow within a MongoDB product
Do not include diagrams in the following situations:
When a workflow is simplistic, such as using the user interface to create a MongoDB user
When there is no interaction with a MongoDB product
Before You Create a Diagram
To create diagrams, you need to access the recommended software and download the required icons and stencils.
Software
Use draw.io to create your diagrams. Draw.io enables you to create diagrams directly in your web browser of choice.
To get started with draw.io, see the instructions in the Draw.io Online User Manual.
Icons, Stencils, and Shapes
Download MongoDB's library of product icons and stencils. These icons and stencils are considered objects.
The product icons are under development.
Stencils are used to represent certain functions and hardware such as the world wide web or a server.
After you download the icons and stencils, you can being making diagrams in Draw.io.
Diagram Checklist
Use the following standards when creating diagrams:
Properties
Each diagram property is located on the right side of the Draw.io main screen under Diagrams.
Paper size: Set the paper size to A4 (210 mm x 297 mm) and Landscape.
Background color: Set the background color to none.
File format: Save all diagrams as editable SVG files, as follows:
Click File > Save As.
Type a descriptive name for the file, and replace
.xmlwith.svgat the end of the file name. The file is saved to your local directory.
File name: Create unique and meaningful file names to differentiate diagrams.
Text Formatting
Font: Set the font to Helvetica.
Titles: Title must be bolded, aligned left, and be at least 24px in size. Use headline-style capitalization.
Objects
Product icons: An icon represents its corresponding product. Product icons are always blue. Following is the Cloud Images icon.
Note
If you find a MongoDB product icon that is not blue, send an email to how-to@MongoDB.com and a member of our team will create a blue version of the icon.
Stencils: A stencil represents a concept or function. Stencils that are not MongoDB products should always appear in black.
Labels: Label all product icons, stencils, and shapes, according to their function within the diagram. Use sentence-style capitalization (that is, capitalize only terms that are proper or are normally capitalized).
Lines and Arrows
Line usage: Use lines are used to connect and display a relationship between two or more objects.
Line width: Line width must be at least 2pt. You can change the width of a line in the Format Panel under Style when you select the line.
Line shape: Keep lines straight unless a line needs to change direction.
Rounded line corners: If a line changes direction, the corner in which the change of direction occurs must be rounded. You can change to rounded corners by selecting the line, going to the Format Panel under Style, and selecting Rounded in the dropdown menu.
Solid lines: Use solid lines to show a direct relationship between objects, as shown in the following example.
Dashed lines: Use dashed lines to group objects that are connected through a network, as shown in the following example.
Dotted lines: Use dotted lines to show how data entered by the user travels, as shown in the following example.
One-way and two-way arrows: Use arrows to represent direct interactions between two or more stencils. If a stencil is attached to an arrow, it implies that the product represented by the stencil needs to interact with another piece of the diagram.
In the following example, the CDN management service needs to interact with the CDN to perform its function. Similarly, the CDN needs to be managed by the CDN management service. The relationship is two-way, so the line has arrows on both ends pointed to both stencils.
