MediaWiki Engineering/Guides/diagrams.net conventions

From Wikitech
Example from MediaWiki at WMF

These are conventions for Wikimedia diagrams in technical writing, as created using the diagrams.net open-source software.

In a nut shell

  • It's a web app. It works a lot like Google Docs, except it's open-source and its for creating diagrams. Get started at https://diagrams.net/.
  • Save your work publicly. You can open a diagram from your device hard disk, or from a cloud service like Google Drive. To benefit from easy saving, sharing, and backups, it is recommended for WMF staff to store their work in their Google Drive, and to make these files public to the world by link so that others can easily copy them to create their own diagrams or to make an updated version of yours.
  • Design.
    • The below #Style reference incorporates this for you, but prefer colors and fonts from the Wikimedia Design Style Guide.
    • Try to keep a good color contrast for readability (e.g. dark text on light background with solid outlines).
  • Legend. Avoid long sentences and text. Avoid many colors or shapes. If using more than one color or shape, consider labelling these or including a legend that explains their meaning.
  • Export as PNG and upload this to Wikimedia Commons for use in articles on Wikitech or any other WMF wiki. Link to your drawio file from the file description (the Google Drive file's share link).

Steps

Go to https://www.diagrams.net/

Create new diagram

  • Logged-in with your work Google Account.
  • Name: Name of subject or concept and a date or year, e.g. "ProjectX ComponentY 2021" or "Draft of X (Jan 2021)".
  • Format: XML drawio (default).
  • Template: Blank (default).
  • Prompt "Use root folder?" - This is asking whether you wanted to use a subdirectory within your Google Drive, or simply in your main drive ("root").

Load the "Lato" font

  • This is a one-time set up for the first text object in your diagram. After this you can always select "Lato" from the list of fonts.
  • Create your first text object (e.g. for the main heading) by clicking "Text" in the "General" shapes drawer.
  • Open the "Text" styles in the "Format Panel". This is the right-hand sidebar. If needed, open it first from its button in the top-right corner.
  • Click on the Font menu and, assuming Lato is not yet in the list, choose "Custom".
  • Choose "Google Font" from the modal dialog.
  • Enter font name: Lato
  • Click "Apply".

Save and share the diagram

  • Save your changes and in a new tab go to https://drive.google.com/
  • Select the diagram.
  • Click "Share" to open the share dialog.
  • In the "Get the link" section change visibility to "Anyone with link".
  • Click "Copy link". We will use this link in the file description when we upload the diagram to the wiki, so that others can find the source and can easily create a copy of it to make future versions of this diagram without having to re-create it from scratch.

Export and upload to Wikimedia Commons

Export the diagram as as high-resolution PNG:

  • In the diagrams.net interface, go to "File" and select "Export > as PNG…". (avoid SVG as this does not render reliably cross-platform, especially when fonts and labelled arrows are used. It also might not render correctly when systems with WordPress or MediaWiki render thumbnails differently than a browser would.)
  • Use these settings:
    • Zoom is 200% (instead of 100%). This ensures text is sharply rendered on modern devices.
    • Border is 0 (default).
    • Size "Diagram" (default).
    • Disabled "Transparent background" (default). If you were to enable this, the text and diagram may become largely unreadable when displayed by someone in dark mode or otherwise displayed on a colored background. For example, if you use the diagram in a blogpost and someone reads it in Reader mode, or in a News reader app. If you want to do this, make sure all boxes in the diagram have an explicit background color (e.g. white instead transparent). And for any heading text to have a shadow or other color behind it to avoid it becoming invisible on a dark background.
    • Disabled "Shadow" (default).
    • Disabled "Grid" (default).
    • Disabled "Include a copy of my diagram" (instead of default enabled). This is inclusion makes the file larger and is not needed as we will share the editable diagrams file via Google Drive instead.
  • Click "Export".
  • Click "Download".

Upload to Wikimedia Commons, after which you can display it on any public or private WMF wiki page:

Examples

Style reference

Text format

  • Font family, for all text: Lato
  • Heading:
    • Font weight: bold
    • Font size: 30 pt
    • Font color: 202122 (Wikimedia Base10)
  • Large text: (e.g. for main heading's caption)
    • Font size: 20 pt
    • Font color: 72777D (Wikimedia Base30)
  • Regular text, such as labels, and legends:
    • Font size: 15 pt
    • Font color: 54595D (Wikimedia Base20)
  • Small text:
    • Font size: 13 pt
    • Font color: 54595D (Wikimedia Base20)

Shape format

  • Styles:
    • Border: 2pt solid, for all boxes, arrows, containers, and other shapes.
  • Text:
    • Text in objects
      • Font size: 15 pt, like Regular text
      • Font color: 202122 (Wikimedia Base10, for improved contrast)
    • Horizontal alignment: Center
    • Verical alignment: Middle
    • Spacing (kind of like box/cell padding, to offset text from edges)
      • Global: 5 pt
  • Arrangement:
    • Minimum height for most objects: 40 pt (to accommodate "Regular text")
  • Variants:
    • Blue:
      • Background color: EAF3FF (Wikimedia Accent90)
      • Border color: 2A4B8D (Wikimedia Accent30)
      • Font color for Large text: 2A4B8D (Wikimedia Accent30)
    • Yellow:
      • Background color: FEF6E7 (Wikimedia Yellow90)
      • Border color: AC6600 (Wikimedia Yellow30)
      • Font color for Large text: AC6600 (Wikimedia Yellow30)
    • Green:
      • Background color: D5FDF4 (Wikimedia Green90)
      • Border color: 00AF89 (Wikimedia Green50, more lively than Green30)
      • Font color for Large text: 14866D (Wikimedia Green30)
    • Red:
      • Background color: FEE7E6 (Wikimedia Red90)
      • Border color: B32424 (Wikimedia Red30)
      • Font color for Large text: B32424 (Wikimedia Red30)
    • Grey:
      • Background color: F8F9FA (Wikimedia Base90)
      • Border color: A2A9B1 (Wikimedia Base30)
    • White (primary):
      • Background color: transparent, none, or FFFFFF
      • Border color: C8CCD1 (Wikimedia Base70)
      • Font: Regular text
    • White (muted)
      • Border color: EAECF0 (Wikimedia Base80)
      • Font: Regular text

Arrow styles

  • Line color: A2A9B1 (Wikimedia Base50)
  • Line style: Sharp or Dotted
  • Line width: 2 pt