Causally Looped: Token Diagrams in Code

Dia Dia Dia Diagrams

Diagrams are an essential tool in token engineering. Not having a way to share, reuse, iterate, extend and collaborate on diagrams hurts. So today we're introducing a way to solve this problem, with simple off the shelf open source tooling and a style guide. Stay tuned to grab the details or go straight to the repo.

Causal Loop Diagrams are diagrams that help us visualize the relationships between entities. ‘+’ represent positively correlated relationships and ‘-’ negatively correlated relationships.

The diagrams help us recognize what behavior should be captured within our token models. Here's a pro guide

What about shareability?

One of the key things missing from the current ecosystem of tools nloopy, lucid charts, and Diagrams is a way to keep track of changes, reuse existing diagrams in new context, and iterate on diagrams async, with the ability to review and annotate changes.

Committing diagrams to a repository in a tractable way would increase productivity and knowledge sharing capability 10x.

Introducing a code based solution ( MermaidJS)

MermaidJS is a diagramming as code tool that allows you to create different types of diagrams using a very small easy to learn/use language. It shares a significant overlap with it's older sibiling PlantUML

It has a very simple syntax, and has the ability to produce charts in a variety of rendered formats, and can even be rendered directly in Jupyter notebooks.

Quick Example (live example)


%%{init: {'themeVariables': {}}}%%
%% comments 
%% This diagram details the graph

graph LR 
  %% :::tr is the class definition that styles a node
  %% the format is nameOfNode[Node label]:::stylingclass

  %% node definition section
  potentialAdopters[Potential adopters]:::tr
  adoptionRate[Adoption rate]:::tr
  adopters[Adopters]:::tr


  %% --> defines the relationship arrow directionn
  %% |+ or -| definnes the type of correlation 
  %% relationship definition section

  potentialAdopters --> |+| adoptionRate
  adoptionRate --> |-| potentialAdopters
  adoptionRate -->  |+| adopters
  adopters --> |+| adoptionRate

%% class def at the bottom adds a transparecy to the nodes
  classDef tr fill:#00000000, stroke:#00000000;

So what's next ?

Check out the repo, for the style guide. Create issues let us know what you think, open to suggestions as this develops.

Eventually this will be in a more commons oriented repo, as we create a basis for moving diagrams into code and creating improvements to this systems.

Some things that we can improve on

We need a style linter for the documents
notes to be added to the diagram directly
improved naming conventions
improved auto layout functionality.

Steps forward

This represents a few steps forward, a future in which we can simply clone or compose diagrams to represent the dynamics in our ecosystem. Will make for a better token engineering ecosystem.

Acknowledgements

Special thanks to @shanejonas for review. Shout out to QuietCataylst,Ratio13, and Elbeth for the feedback for this concept.

Zane