Most workflow or DAG tools have the ability to add notes or comments to each step so you can record details of why exactly complex interactions or filters are set up the way they are. Many also provide a separate “note” type that can be placed anywhere on the canvas -- a “sticky note” to add context details for future co-workers.
We have a number of complex workflows with some very specific cases and conditions, but they are fragile because we can’t record notes about these specific details and condition directly where they happen. This has caused things to break unexpectedly when changing in the past, and has made it longer to debug & fix workflows that have broken due to some other method.
Recording these notes in separate design documents is not a great solution -- people don’t do it consistently and they don’t think to reference them when they have questions.
The current comment functionality is not sufficient: they’re basically hidden and you have to remember to toggle comments to see anything. Most other workflow / DAG tools show the notes directly in the main UI, and in the details of the step, so you can view it and update it as you’re making changes to the step itself.