How do you keep track of your automations?

macOS
1

So, we’ve created automations using Shortcuts, Automator, Keyboard Maestro, BetterTouchTool, Rectangle, Alfred, Hazel, Bash scripts, Python, etc. We’ve modified keyboard shortcuts and developed sophisticated x-url schemes. And some automations start in one program and end up calling other ones to finish the job.

It all works great … until it doesn’t… and then you have to track down what went wrong.

  • How do you keep track of what you did where?
  • And how do you make things clear (for your “future self” that is doing the troubleshooting) about the logical flow of each automation?

At times, I have been tempted to keep a binder cataloging my automations, complete with arrow diagrams illustrating the steps. That way, if something breaks, I’d have my own notes as a starting point.

1 Like
2

If the tool supports comments, then I put comments in.

I also document in Obsidian, although any such tool would suffice.

Using on machine tools, as opposed to a binder, allows for easy copy and paste. As well as accessing external documentation via links.

3

Okay, so that’s like keeping a binder. Do you outline the steps in order or draw a directed graph to clarify branch points?

Comments are a given, although some tools don’t make that easy.

4
  • I document my automations in Obsidian.
  • I tend to be consistent in the tools I use for particular things.
  • Comments in the code.
  • Documentation of the automations.
  • Diagrams (usually Mermaid diagrams) of key flows.
  • Standardised naming conventions wherever viable to employ them.
  • Cross linking across documentation to sign post to related or additional information,
  • Cross linking automations utilising Hookmark direct to relevant documentation and related automation content.

You can read more about this latter one here:

I also have posts where I go into more detail on hooking particular app automations.

All of my BetterTouchTool automations are really triggers, so get minimal documentation, and Hookmark can hook script files like any other file.

I would not choose to use a physical binder. About 20 years ago I used to have a folder I carried with me at work. It documented the systems I worked on. It had data flow diagrams, entity relationship diagrams, conversion tables, data dictionaries, etc. In fact I happen to have it close to where I am sitting right now…

image
image4032×3024 3.24 MB

By having pages in plastic wallets and using full O-rings with thick plastic covers I had something much more rugged than a more traditional cardboard (maybe covered in a thin plastic skin) binder.

But every time something changed I had to update and reprint. I had to know exactly on which page to find every piece of information (which I did as I used it constantly).

I have been paperless for over 15 years. Being able to carry the documentation with me on a device meant I could keep it up to date as a single source of truth. I could search across everything and link disparate documentation together (including online) without having to print and carry more and more paper. There are just so many advantages for digital content over analogue content for me that I simply would never choose to document in a non-digital format.

3 Likes
5

Thanks for the link – fascinating read!

Hook aka Hookmark has been on my “someday/maybe” list for a long time. While I could think of a few use cases, it never found the need to be so compelling. But it’s something to consider again.

As for binders, I agree that digital is better nowadays. I don’t use Obsidian. Maybe I’ll try Snippets Lab, where I tend to store my coding snippets and “colophon” for setting up a new Mac, etc. Seems like it might fit there.

Alternatively, I could set up a Quarto project to document it. That would give me version control, too.

Mermaid diagrams would be useful. I know Marked can display them, along with Quarto.

Thanks for the tips.

6

Maybe check out this post too then.

1 Like