Categories
Architecture Automations Notion

Add a sequence diagram to Notion

In order to express their ideas about a project’s architecture, developers can utilise the UML sequence diagrams.

There are different ways to create and publish these diagrams, ranging from paid apps(8$/month, 100$) to free Confluence apps.

It can be a formidable task to choose from all of these options. As a programmer, a good solution could be to write the diagram in text, and later commit or convert it to an image.

PlantUML ☘️

With PlantUML, sequence diagrams can be defined in a text format, and output to .svg or other image formats via a command line tool.

Consider the diagram:

Alice and Bob sequence diagram

This can be defined in a very human-readable format inside a diagram.puml file:

@startuml
Alice -> Bob: Authentication Request
Bob --> Alice: Authentication Response

Alice -> Bob: Another authentication Request
Alice <-- Bob: Another authentication Response
@enduml

And then converted into .svg using the command line tool:

java -jar plantuml.jar -tsvg diagram.puml

There are different extensions for PlantUML. In Atlassian, one can write the definition and it will be output as an image into the document.

For the Notion workspace, there is no official integration. Instead, we can write a script and use their API.

Notion table 📝

First, the diagram should be described using either the PlantUML text format, or as a relational table.

If we want to use relations between UML objects, we need to use the latter.

Services table

In the first table, a single column with our services Alice and Bob needs to be described.

Alice and Bob services

Diagram table

In the second table, the actual diagram will be described with actors from the related services👆🏽table.

Alice and Bob diagram

Note field will be used as the action name.

Output from the tables ⚙️

To convert the tables into UML, we can use a Python script to download the Notion table, convert it to PlantUML, and output the UML image.

notion.py, “Unofficial Python 3 client for Notion API v3”, can be used to:

  • request the tables from our Notion workspace
client = NotionClient(token_v2=token)
cv = client.get_collection_view(sequence_diagram_table_url)
  • translate the tables into PlantUML
for row in cv.collection.get_rows():
    service_origin_block = row.origin[0]
    service_end_block = row.end[0]
    pum+=("\"{}\" -> \"{}\": {}\n".format(
        service_origin_block.name,
        service_end_block.name,
        row.label))
  • output the final image using plantuml.jar
subprocess.Popen(["java", "-jar", "plantuml.jar", "-tsvg", "out.puml"])

Result

After calling our script:

python notion-diagram.py https://www.notion.so/952a65008448439b9f0d82c9755a525d\?v\=0de421bd4e2b485fb624ff4edc527e0d Alice

we get our sequence diagram result

Alice and Bob diagram from Notion table

Optionally, the output could be uploaded to Notion or other services.

The script is available in tonisives repo. It is based on the official Notion blog post.

Conclusion 🖋

It is possible to create sequence diagrams in a text format, and convert them to images later.

What are the positives? 👍🏽

  • Can edit diagrams in a text format.
  • Don’t have to load a web page or a different app.
  • Can generate UML from command line, then transfer the image anywhere.

What are the negatives? 👎🏽

  • Cannot use a GUI program
  • Requires scripting and shell usage knowledge
  • More difficult diagrams can be hard to write

Related tweet:

Categories
Automations General

Workflow automations

Some of the smaller, repetitive tasks as a programmer can be automated and by doing so productivity improved and frustrations reduced.

I am talking about tasks like moving the cursor, writing keystrokes and manipulating text and apps. My purpose is to use the trackpad less and keyboard more. By doing so you can focus more on your ideas and less on pointing the mouse cursor.

Programs

MacOS enables some automations by some of its native apps. I find third-party apps more convenient and feature-rich. I use:

  • Keyboard Maestro(KM) for activating apps, text manipulation, clipboard history and much more. It costs 36$ but considering the time and focus it saves it is worth it. Most of my automations use this app.
  • Karabiner-elements to map some keyboard keys to more useful functions.
  • ShiftIt to resize and move my windows with keystrokes.

Remapping redundant keys

Some of the keyboard keys are rarely used. They can be mapped to more useful ones to reduce finger gymnastics. Karabiner-elements app is used for that.

I use these complex modifications:

Karabiner-elements complex modifications

Most useful things here:

  • Map caps lock to control on hold, escape on click. Good for TouchBar users.
  • Left control to hyper key for extra modifier key. I use this to open and bring apps to front.
  • Left and right shift keys to parentheses ( and ) if pressed. Normal shift behavior if held.

There is more that can be achieved via karabiner-elements, for instance ctrl-hjkl for arrow keys navigation.

Code navigation

Moving the text cursor with trackpad is slow and imprecise. There are solutions to make it more convenient, like using vim keybindings or native MacOS text navigation shortcuts.

I went for a custom setup:

  • ctrl+w/s to scroll the document. This is a KM macro that simulates the scroll wheel.
  • ctrl+e/d to jump between text paragraphs. In IntelliJ this shortcut is “Move Caret Backward/Forward a paragraph”. Otherwise it is “alt+up/down”
  • ctrl+r/f to page up/down. Mapped in KM.
Code navigation shortcuts

I map different macros to these keybindings so they will work across all apps – code editor, web browser or notes.

Code navigation shortcuts

Here are my KM code navigation macros.

Switching between apps

I use hyper+keystroke to activate and move the cursor between apps. This is convenient because you don’t have to visually identify the app icon, compared to cmd-tabbing. Moving the cursor to the app is useful in multi screen environment.

I use hyper+g to search in google.

I use hyper+l to toggle clipboard history. This saves you time because you can copy multiple items and don’t have to navigate back and forth between apps.

Googling a solution. Trackpad is only used for selecting the text in the web page.

There are many more shortcuts I use in my workflow. Here are my global KM macros.

Conclusion

Automations have improved my workflow considerably. I can focus more on my ideas and less on navigating the OS or the code editor. I would recommend trying these out to any programmer who feels that expressing her coding ideas could be faster.