Also move transitions to the bottom of the document, and try to clarify the documentation for split, join and activity kinds.
I tried starting a better one, but the workflow code is a complete mess so I have no idea how this thing works without significant study and testing. Thus, not trying to write a brand new and complete doc, maybe later.