Creating diagrams is a helpful way of thinking about and communicating complex systems. You might diagram a [[situation model]], [[systems map]], [[user journey]], [[mind map]], [[process map]], [[software architecture]], or database schema (i.e., [[entity-relationship diagram]]), to name a few. I find that creating a diagram helps me discover missing components and unexpected connections in a way that text does not. ## First sketch the diagram To create a diagram begin with a [[sketch]]. Using pencil and paper, a whiteboard, flip chart, or sticky notes promotes collaboration and rapid iteration. The goal is simply to understand the major components and their potential interactions. (Be sure to clearly define what is--and is not--within the scope of the diagram before you begin). ## Capture the diagram for continued iteration Once you have the rough sketch, you may want to capture the diagram such that you can rapidly integrate feedback and other changes as the system becomes fully fleshed out. I prefer using tools that convert text to diagrams so I can describe the system rather than worry about the layout and visual design. There are many tools like this available for specific use cases, see *Tools for diagramming*, below. You may prefer working in a visual diagramming tool (like Google Slides) or need to collaborate with others who prefer visual diagramming tools. ## Formalize the diagram You do not necessarily need to create a polished final diagram, especially if you expect continued changes to the diagram or the system it describes. Often the value of diagramming is in the thought exercise, conversation or collaboration that occurred while creating it. If you do need to deliver a finalized diagram, take the time to consider how to communicate with your audience using the diagram. Use colors and shapes consistently, include icons thoughtfully, add a legend, and include sufficient annotations to make the diagram self-explanatory. You might also break up the diagram into components, visually group related content, and collapse/expand hierarchical relationships to communicate different levels of complexity. [Kumu.io](https://kumu.io/) is the best solution I have found for making high-quality presentable diagrams; it has a presentation feature that allows you to walk users through the diagram piece by piece. See my guide to [[Kumu]] for features and guidance. Kumu is free to create public diagrams and for students. ## Tools for diagramming These are my preferred tools, depending on use case. ### Text-to-Diagram - [mermaid](https://mermaid-js.github.io/mermaid/#/) (for general use cases and use with [[Markdown]], try the [mermaid live editor](https://mermaid.live/edit)) - [Viz-js](http://viz-js.com/) (for general purposes) - [dbdiagram.io](https://dbdiagram.io/home) (for entity-relationship diagrams) - [c4-builder](https://adrianvlupu.github.io/C4-Builder/#/) (for software architecture diagrams) - [plantuml](http://www.plantuml.com/) (for general purposes when an online editor is desired) - [Structurizr](https://structurizr.com/dsl) (for software architecture diagrams when an online editor is desired) ### Visual Diagramming - [excalidraw](https://excalidraw.com/) (for general use cases) - [Miradi](https://www.miradishare.org/ux/home) (for situation models and results chains) - [Google Cloud Cheat Sheet](https://googlecloudcheatsheet.withgoogle.com/architecture) (for designing Google-based systems) - [kumu.io](https://kumu.io/) (for systems maps and polished diagrams) ### Other Options - [Google Slides](https://docs.google.com/presentation/) - [Miro](https://miro.com/) - [Mural](https://get.mural.co/) (check out the templates for common diagram types) ## Integration with static websites Embedding a diagram in an [[interactive report]], [[static website]], or online [[project documentation]] is a great way to share a diagram, especially if the diagram supports interaction. Before selecting a diagramming tool, consider how the diagram will be integrated with your documentation. If you are using a [[static site generator]] like [[mkdocs]] or [[docsify]], you can create the diagram in Markdown-compatible format (like Mermaid) or include the static file in your assets folder. For interactive reports consider using a service like [Kroki.io](https://kroki.io/), which has a free [[web API]] for returning diagrams from text for many types of [[domain-specific language]] or language-specific servers like the [PlantUML online server](https://www.plantuml.com/plantuml/uml/SyfFKj2rKt3CoKnELR1Io4ZDoSa70000). To preserve interactivity, some other tools (Kumu and the paid tier of Structurizr for instance) allow for embedding through an [[IFrame]].