Create new visual design language for representing flows

[pospi]

Forking this off from #502 as there will likely be a lot of chatter in this and they are two separate tasks.

Currently we're heavily considering string diagrams, like this one:

More reading on this style of diagram can be found at https://arxiv.org/pdf/1803.05316.pdf

There have been quite a few different representations for flows created over the years, such as:

• http://valueflows.pythonanywhere.com/vocab/egg2worm-flow/ and various other examples on http://valueflows.pythonanywhere.com/
• The diagrams on http://locecon.org/
• Various places on http://valueflo.ws/

It would be ideal to get to a shared visual design language for these types of diagrams (colour palette, shape & line styles as well as 'overall style') so that we are all modeling in a consistent way. We could just follow the style of the old NRP diagrams, but I think there's an opportunity here to do something more considered & have a re-think with some designer input. Plus, computer-generated diagrams similar to these will likely become part of various interfaces in future.

Other relevant comments on this topic to date:

• Add high-level examples section to website #502 (comment)
• Add high-level examples section to website #502 (comment)

[pospi]

Trying to give a bit more detail on the components of VF in a way that is (hopefully) useful to designers. I see the need for two distinct types of diagrams:

• "Flow design" diagrams, which simply depict the planned flow of resources & processes through an ecosystem. Should be clean, simple & useful for business analysts in designing systems.
• "Flow state" diagrams, which show particular agents & resources moving through the flows. Should give "concreteness" to the "flow design" diagrams by allowing step-by-step explanations to be walked through. I think of these as overlays that use the same flow layouts from the design phase to aid in comprehension. They basically depict the key states that a system can be in.

These are just my personal thoughts, there might be better ways. For example, maybe showing the roles of agents in these systems is very important in the design phase. Trying to strike a balance between giving information and imposing my own ideas is hard :/

Again, without trying to impose too much of my own subjective viewpoint, here are some of the VF building blocks; as well as their key attributes and the states they can be in (referencing the "egg to worm" flow from above):

• The main building blocks are the "flow items": Resources (green squares in the diagram), Events (orange diamonds) & Processes (blue circles).
• Resources:
  • Have a "type of resource", which can be any description of a "thing".
  • There are also "skill" resources, which denote types of work effort.
  • Also have a quantity, which is typically not shown in "flow design" diagrams but may be relevant in "flow state" examples.
• Processes:
  • Describe the types of things that happen in a network- they alter resources
  • Have a "type of process", which can be any description of "something to do"
  • May be fed by 0 or more tangible resources
  • Often also fed by "skill" resources which indicate the types of work needing to occur
    • Historically these have not been shown as the simple case (1 type of work needed to carry out a process) doesn't really need detailing- the process & the work skill can be considered equivalent in these cases
    • However it may be useful to show work inputs along with the agent doing the work in "flow state" diagrams
      • Certainly display of "skill" resources is needed to show how multiple agents can commit to doing some work to complete a process. But if it's just one agent, maybe they can be shown to have committed to the process instead.
  • Progress through "planned", "committed" and "completed" states as resources are provided and work is undertaken
    • Note they don't really have any state of their own— these are inferred from the input Events
• Events:
  • Link resources to processes by describing which action connects them
  • Have an "action verb" that is mostly (but not always) one of the VF action verbs.
    • Actions have the concept of whether they increment or decrement a resource which can be useful in planning
  • Usually progress through "planned", "committed" and "completed" states as resources flow through a system
    • Sometimes things are not pre-planned, so events can start off as "committed" in some cases
      • Likely only relevant in "flow state" diagrams if wanting to show how extra work happening outside the planned flow can occur
  • Are typically downplayed in diagrams, often omitted entirely (especially in systems where "produce" and "consume" are the only action verbs commonly used). In the above "lemon meringue" example they are the joins between lines & boxes.
    • In some flows, increment / decrement may be displayed as +/-
    • In other flows, the action verb might be more important
    • If we could agree on a consistent way to represent these that works for any system, that would be amazing. But would settle for a few styles of varying detail to pick from.

There are also some less prominent "flow items" that can be part of a system:

• Transfers sometimes feature in place of Processes; you can think of them as processes which move a resource from one agent to another. However they may require a depiction which makes agents visible; since the input & output resource are the same (only the owner changes). An alternative would be to show the "give" event going in to the transfer, and the "take" event coming out. You could place agent icons next to each event to show the sender & receiver.
• Exchange of resources can be modelled by Agreements which simply enable sets of Events to be coordinated. In the simple case of an exchange it looks much like two Transfers. There are actually a minimum of 4 events at play here: two incoming "give" events and two outgoing "take" events. But there may be more, if multiple things are exchanged for another. These too probably look much like Processes.
• For more complex Agreements the "process-like box representation" probably works just as well. In the end they are just a means of grouping Events.

And some other parts of the vocabulary for special cases, which we may or may not want to consider at this stage:

• One Event may be linked as an "Appreciation" for another event. Relevant to gift economy flows. Could probably be displayed fairly simply as a connecting line.
• Claims may be created, which specify future Event(s) desired as return for some Event that has already occurred. For example, you could say "I gave you 10 apples and I want $5 for them some time in future". This may overlap with the "flow state" diagram styles, because an open claim kinda feels like a "planned" event to me. Later in the flow, real Events would be filled in to complete the claim.

And finally, there is the Plan concept, which is probably best represented as boxes which group different parts of flows. Basically a plan is just there to group a body of work into a single logical task.

I hope this makes sense and is not too overwhelming! Please correct, elaborate and discuss as needed (:

[elf-pavlik]

Thanks for raising it @pospi I've been experimenting with something like below:

It uses sort of pink for resourcey stuff (including personal skills), purple for processey stuff, orange for agreements, flows - blue intent, orange commitment, green event.

While doing that I also lean more towards not treating agents, resources and processes as disjoint. So we can also treat agents as 'very high level process' which can have inputs and outputs. Processes should preferably form circular economy cycles, and Agreements should preferably form circular reciprocity cycles. Simplest example:

Flows with service actions go directly process to process without involving any resource

Also this image from our website:

Could have multilateral variants like:

[bhaugen]

@elf-pavlik if you conflate agents with high-level processes, then do processes have agency?

Or if you conflate resources with processes with agents, than do resources have agency?

(To be more explicit, I think agents, processes, and resources are distinct concepts for very good reasons.)

[elf-pavlik]

Usually progress through "planned", "committed" and "completed" states as resources flow through a system

This sounds like;

• planned - Intent (not yet committed)
• committed - Commitment
• completed - EconomicEvent

Where Satisfaction and Fulfillment allows M:M to refine it between those phases and we may still need some kind of further withing one phase refinement constructs #464

[elf-pavlik]

@bhaugen to avoid hijacking this issue let's continue on disjointedness in #508

[pospi]

@elf-pavlik planned / committed / completed is exactly as you describe. Even though those are separate distinct record types in VF, conceptually I feel that they just indicate the state of a particular event / process.

Unfortunately the diagrams you posted don't seem to have legible lines- are they white or something? Any chance of a reauthoring for Github's display context?

[fosterlynn]

A few comments and clarifications on this #507 (comment) .

I see the need for two distinct types of diagrams:
"Flow design" diagrams
"Flow state" diagrams,

I like this overview and distinction. Is it more of a priority to focus on the former first, as that helps groups think about their processes and workflow as described in VF? Or focus on both at the same time? If just the first, we can simplify a lot of the explanations.

For example, maybe showing the roles of agents in these systems is very important in the design phase.

It might be useful to some people. Examples I can think of are an herbal network we worked with that had "growers", "harvesters", "drying sites", "sellers", with flows between them. Or maybe showing roles like "customer" or "supplier" as flows go out of scope for the agent doing the diagram. Can we think of doing this exercise with the ability to add in layers or not, like "click" and it shows agent roles? Or "click" and it hides the resources and just shows flows?

[edit: Actually we could show the herbal network roles as types of work too, which are just events with resource classifications. Instead of the agent roles, which the herbal network used a lot because they were focused on transfers between those agents more than the processes used by those agents to do their thing. Hope that wasn't even more confusing!]

Often also fed by "skill" resources which indicate the types of work needing to occur

• Historically these have not been shown as the simple case (1 type of work needed to carry out a process) doesn't really need detailing- the process & the work skill can be considered equivalent in these cases
• However it may be useful to show work inputs along with the agent doing the work in "flow state" diagrams
  • Certainly display of "skill" resources is needed to show how multiple agents can commit to doing some work to complete a process. But if it's just one agent, maybe they can be shown to have committed to the process instead.

I think this makes things too complex. And I'm not sure that the one-type-of-work processes are really the norm, although they will be for some domains. My opinion: let's just stick to the structure we have and not second guess the differences. Especially to start. Also I think sticking to the observation layer might be best to start with also, rather than including commitments, etc. For the "flow design" diagrams, this is just analytical anyhow, so we could think of possibly mythical and aggregated observation layer items, but still thinking of "real" processes.

Sometimes things are not pre-planned, so events can start off as "committed" in some cases

Sometimes things are not committed either (which should actually be thought of as part of planning). Sometimes there are just events.

Events:
Are typically downplayed in diagrams, often omitted entirely (especially in systems where "produce" and "consume" are the only action verbs commonly used). In the above "lemon meringue" example they are the joins between lines & boxes.

Just to clarify, I don't think you can get a line without the events. In that diagram I think of the lines with the resource classification text as events, not as resources, although clearly there is resource related info there. And 2 events form each line. Might just be different ways of conceptualizing, but thought it might be useful to mention.

[fosterlynn]

Just to clarify, I don't think you can get a line without the events. In that diagram I think of the lines with the resource classification text as events, not as resources, although clearly there is resource related info there. And 2 events form each line. Might just be different ways of conceptualizing, but thought it might be useful to mention.

@bhaugen thinks I am confusing things more. Sorry about that! When I said you can't get a line without the events, I meant that literally, the visual line. Could display just the line with no labels, could add textual information from there for the resource classification/specification (like "lemon filling"), and from there information about the events if you want.

[bhaugen]

When I said you can't get a line without the events, I meant that literally, the visual line. Could display just the line with no labels,

Like this:
http://valueflows.pythonanywhere.com/vocab/processes-only/
There you can see some processes with lines connecting them. Each line has 2 events and one resource behind it, that were necessary to the code that constructed the line, but are not shown on the diagram.

[elf-pavlik]

planned / committed / completed is exactly as you describe. Even though those are separate distinct record types in VF, conceptually I feel that they just indicate the state of a particular event / process.

I think we should stay careful when we talk about events, since VF only has notion of past (observed) events, and any future (plans) get represented by intents and commitments. I find flows as safer term to talk about intents, commitments and events in general without distinction if we talk about future plans or past (sometimes present) observations.

Unfortunately the diagrams you posted don't seem to have legible lines- are they white or something? Any chance of a reauthoring for Github's display context?

I actually mostly tried avoid adding lines not to create extra noise, since flows act as lines (inputs & outputs), usually one can see how things connect just by looking at the glyph with a little wave: blue: intent, orange commitment, green - event. I think about adding a timeline slider to that map which when used could show when each of the flows occurs / lasts. Since my map also represents some recurring flows, I'd like to have a way to give bubbles next to them (also 3 colors) with how many I, C, E we have in the same place. One could also hover to see list of all the flows.

[elf-pavlik]

Processes should preferably form circular economy cycles, and Agreements should preferably form circular reciprocity cycles.

Expanding a little bit on my comment above. Since we live on a globe (plant Earth) and I hope aim at circular economy and circular reciprocity, when we take independent perspective we don't really have forward and backward flows. With respect to processes, we always have I > P > O direction. When it comes to agreements and reciprocity, in general we have mutually reciprocal flows. Currencies seem like a special case where one may consider flow involving currency as 'non primary'. Still as long as we stay connected to use value, it seems that we have mutually reciprocal flows and no forward or backward notion of reciprocity if we take independent perspective.
We may see certain direction with provide > receive but in general case of exchanges we have at least two of those directions agreed upon, sometimes more.

[pospi]

Also I think sticking to the observation layer might be best to start with also, rather than including commitments, etc

I don't think it's necessary to show any of those in the design phase. I have been using "Events" too loosely, and agree with what @elf-pavlik is saying: it's actually "Flows" I have been talking about. When I think of events / commitments / intents in the context of diagrams, I think of them as "the states a flow can be in".