improve introduction to Value Flows

[ahdinosaur]

i'd like to write up a better introduction to explain the high-level concepts of Value Flows for newbies.

at the moment i'm attempting to explain the Value Flows concepts to @pietgeursen and @sarah-arrrgh for cooper, @donlewi for resourceful, @ashlynbaum for happy-flat, and probably more soon. it's been great as it's providing me valuable feedback on where we can improve, but i'm also aware the learning curve is quite steep, as i remember it took me a few months of weekly meetings with @bhaugen and @fosterlynn before the concepts started to make sense. i'm hoping we can improve our on-boarding so more people can build systems based on the Value Flows vocabulary, thanks y'all for playing along. :)

at the edge of my thinking, i divide the description of Value Flows into a few major sections:

1. introduce what is Value Flows: a work in progress set of minimum concepts (domain models) to describe socioeconomic systems. we aim to describe an abstract vocabulary, in that it only describes the simplest and most general set of verbs and nouns that are necessary in order for disparate projects and communities to define concrete vocabularies based on their specific use cases and local culture. our target audience is developers building apps that involve socioeconomic systems.
2. introduce subjects of our systems: agent & resource, also as a way to introduce type objects.
3. introduce interactions, or what to do with agents and resources: transfer, transform, and transport.
4. introduce conversations, or events that must happen to reach an interaction: intent -> commitment -> flow.

i find it helpful to describe the concepts through examples and analogies. here's a recap of a quick conversation today with @pietgeursen:

• "an example of an agent is me, Mikey! i have a name, an email, etc. each agent, like everything in Value Flows, has an associated type object. for agents, these can correspond to the different type of agents in Open OS, namely Person, Pod, Community, and Network. on the type we can specify properties of that level of organizing structure."
• "a resource is a physical thing, a resource type is the abstract ideal of that thing. when you go on Amazon you browse through resource types you can buy, the physical thing that you receive in the mail is a resource. when you go to the library catalog you browse through types of books, which correspond to physical books you can check out. these resource types can relate to each other as a taxonomy, as we see with categories on Amazon and genres in the library."
• "a transfer is when a resource changes hands. for example, i give you three dollars in exchange for a coffee. the coffee and money resources are still the same, but they've changed owners."
• "a transform is when a resource changes composition. for example, i input the resources of coffee grounds and hot water into a coffee machine resource in order to output hot coffee. the hot water is consumed during use, the coffee grounds are turned into waste, and the coffee machine is used but still available for more coffee."
• "in order to reach a transfer or a transform, we must have a conversation. it starts with an intent: a want like 'i'd love some coffee' or an offer like 'i have heaps of coffee'. once an offer and a want match, then two parties make a commitment to each other, almost like a contract: 'i'll give you a coffee in exchange for receiving 3 dollars' and 'i'll receive a coffee in exchange for giving 3 dollars'. now that we've committed to what we want to do, we only need to do the flow! one side gives the coffee and receives 3 dollars; the other side receives the coffee and gives 3 dollars."

hmm, thoughts?

[gcassel]

My main thought initially is that this is a crucially important objective-- and timely, too, as Value Flows gains visibility through various networks including Collaborative Technology Alliance.

Your tentative roadmap for this looks great @ahdinosaur :) and I'll try to help out to the best of my ability.

[ahdinosaur]

I'll try to help out to the best of my ability.

@gcassel your help here would be much appreciated. :smile_cat: since you yourself are a newbie to Value Flows, are there any recent memories of when concepts "clicked" or any current struggles for concepts that are still confusing?

[bhaugen]

@ahdinosaur this is a great idea and initiative. I liked everything you wrote. Keep going!

[fosterlynn]

@ahdinosaur awesome, this is really needed! Please feel free to assign me specific things to document or visualize if you like. Although I think it's critical that someone like you drive it.... :) And I love that you're trying things out on real people.

And @gcassel you're a great person to help too, I continue to appreciate your eloquence in many forums.

[gcassel]

@ahdinosaur I'll try to think more closely on your questions later. I think it's pretty hard for me to add value right now because you're off to a great start. Thanks @fosterlynn for your kind words, and for all that you do here.

I'm highly oriented towards parsimony and simplicity whenever possible, and I think you all are as well. With value flows' objectives, it seems to me that we should focus more on improving the clarity and user-friendliness of the actual vocabularies instead of putting much time into explanatory materials-- except for examples!

Examples are critically helpful, and your example in the OP here Mikey is awesome. Ideally, I think it'd be great to create a bunch of examples on that same level of abstraction/organization, to help people think more clearly about the nature of resources, processes and transactions.

So, I think that the actual vocabularies, and related examples, can effectively illustrate most of value flows' potential. However, it'd be helpful IMO to have some high level overview "Why Should I Care?" context for newcomers and general visitors. Most people IMO seem to view money rather literally, and to rarely think of all the abstractions in everyday economic transactions. They may prefer to think about political policies regarding the distribution of nation-state currencies, or personal moral decisions, than to rethink our language and systems for relating to peers and communities.

If anyone knows of suitable high level overview "Why Should I Care?" materials for the general public, I'd appreciate being pointed towards them. If not, I can start looking into finding, remixing or creating things. (For instance, hmm, the front page of http://mikorizal.org/ seems relevant.)

[ahdinosaur]

from https://github.com/valueflows/valueflows/issues/104#issuecomment-168193101

how i've been explaining Value Flows to people: there's are agents and resources, there are actions the agents can do with the resources, and there are things you can say in a conversation about the actions.

so i'm interested in our vocabulary beyond agents and resources to focus on actions the agents can do with the resoures and things you can say in a conversation about the actions.

[bhaugen]

@ahdinosaur - I'll help with your direction. But I'm curious about who you are trying to explain VF to. Why are they interested? What might they want to do with what aspects or potentials of VF? Any possible use cases? Or is it more like, telling them about something you are working on, and trying to get them to be interested, but they basically aren't?

[danalexilewis]

@bhaugen I suppose I am one of them. I am interested in immediate adoption of VF within our consulting unit as a way of documenting clients needs. In resourceful I have been playing with marrying up the VF/REA vocabulary with Gherkin with the aim of taking user stories to the next level with clients - my dream is to have clients start to think about there apps in this way.

My long term ambition is to use VF as a foundation for a creating distributed systems to aid people in the management and planning of there things. The decentralization of knowledge.

So in your last comment I am definitely one of the former. I have also had trouble trying to explain VF to others. eg my Dad who was interested in what I am doing and a self taught economist. I feel like I missed some key nuance when trying to explain it, as he just wasn't as excited about VF as I am. And I had expected he would be - so that was interesting, definitely going to go and quiz him again about it.

[ahdinosaur]

@bhaugen i'm currently collaborating with friends @pietgeursen and @sarah-arrrgh who are working on food cooperative systems, @donlewi who introduced himself, and @ashlynbaum who is working on shared living systems. i'm supporting their projects, which all have use cases for Value Flows because they are building apps for local socio-economic systems. if it was easy to get started using Value Flows (if it were "the path of least resistance"), i'm hopeful that they'd all start using it immediately, but i think the barrier is more about Value Flows being difficult to understand and hard to immediately apply in a typical project. luckily my friends seem happy to tag along for the ride. :smiley_cat:

[bhaugen]

@donlewi @ahdinosaur - in all of the situations you mentioned, I think modeling the use cases using VF concepts might help to explain to them, as well as explain to ourselves.

VF is a set of general abstractions. As such, they need to be minimal and adaptable to many contexts. But the problem is that people need to figure out how to apply the minimal set of abstract concepts to their particular situation, and that takes work.

@fosterlynn and I (for example) work in spirals, applying an evolving set of general and minimal abstractions to a series of particular situations, which you can read about here. Then we go back and regeneralize, improving the general abstractions based on what we learned from the last spiral into the details. For us, the Value Flows project is the latest spiral back to the general abstractions, following our experience with Sensorica on the NRP software project.

I think applying the VF concepts collaboratively to new sets of use cases should help to explain better to those sets of people. (And VF is also the first project where we have so many collaborators on refining the concepts, which is great!)

A bit more:

@donlewi - for your Dad, maybe, this an article I wrote in 2005 (and should update) that touches on some aspects of economics. I think about VF in terms of economics, so if I knew more about his interests, I could probably do better.

@ahdinosaur - we applied an earlier version of the VF concepts to food networks. It's probably not exactly the same as your food cooperative use case, which might be more like a buying club (not sure), but it might be helpful.

But I'm very interested in actual use cases where people might want to apply the VF ideas. More interested in those than in the kinds of use cases we have been documenting, which continue to be useful, but are not usually situations where somebody wants to use VF in real life.

[bhaugen]

Another related angle: one of my past collaborators, James Tauber, said that every higher layer of abstraction loses 90% of the audience that understood the next lower layer. While he just made up the 90%, I think the idea is fairly accurate. At the same time, if distilled well, the higher abstractions are a lot more flexible and multi-purpose than the lower and more applied layers. As always, I think sweet spots exist between the too-abstract-to-be-useful and the so-specific-it-only-applies-to-you-last-week.

[gcassel]

^ I would definitely upvote that comment if possible.

[fosterlynn]

@bhaugen i'm currently collaborating with friends @pietgeursen and @sarah-arrrgh who are working on food cooperative systems, @donlewi who introduced himself, and @ashlynbaum who is working on shared living systems. i'm supporting their projects, which all have use cases for Value Flows because they are building apps for local socio-economic systems.

@ahdinosaur and friends: Would it be helpful if we started an issue for each real use case that someone wants to explore in VF, and people can chime in and help see what the fit might be? I for one would be happy to plug in and try to do some concrete mapping between requirements and VF, although I'll be limited in time until the 13th. And if not, no worries, of course. :)

[gcassel]

@fosterlynn I think that could be pretty helpful especially if you create a 'use case' label to apply to those issues :)

[fosterlynn]

@fosterlynn I think that could be pretty helpful especially if you create a 'use case' label to apply to those issues :)

Done!

[ahdinosaur]

as i keep having conversations where i introduce people to Value Flows, i spent some time today on a better introduction in the README, feedback appreciated. it assumes we follow through with https://github.com/valueflows/valueflows/issues/103 and https://github.com/valueflows/valueflows/issues/104, which i still feel is a better way to structure and explain the project.

[bhaugen]

I'm good with your new intro. Thanks for writing it. May come back at it later as more people comment, but have no suggestions for improvement now.

Please tell stories about your intro conversations, too, if you get any clear feedback.

[fosterlynn]

@ahdinosaur yes, thanks for improvements!

I need to update that model a bit re type objects and Transfers, will do sometime, doesn't seem urgent. And we of course are still working through what wants type objects and what wants subclassing in LOD land. I think we will end up with subclassing (or subpropertying) if there are a small number of options, otherwise use the type objects. But in either case, it is just an implementation choice, we will need to support continued user experimentation in types of everything.... (IMO)

Agree with @bhaugen it will be very useful to hear how people understand the VF project.

[gcassel]

Good progress, thanks so much @ahdinosaur :)

One little thing which may be helpful soon, is for the "Who uses this?" section to end by foreshadowing some potential associations moving forward. For instance there's been quite a lot of positive talk about VF in Collaborative Technology Alliance on Hylo. I definitely don't want to dwell on CTA though: maybe we'll have other growing bonds with Mutual Aid Networks and other groups too...

[bhaugen]

@gcassel I'd love to other actual users nor commitments for use of VF. But as far as I know, we have no such other commitments. I don't think "positive talk" is worth mentioning. Gimme at least a commitment. Better yet, some progress in actual use.

[gcassel]

@bhaugen I think it's perfectly fine to share possibilities and potentials if they're reasonably well-described: certainly not in the manner I briefly referenced them above. However I have no desire to push for that.

[bhaugen]

I have no problem sharing possibilities and potentials and even rumors in gitter or link dumps or something casual like that, especially if they are accurately described. I don't think they belong in the introduction.

[gcassel]

I think I get what you mean, and I think that my perspective varies subtly in a way which isn't worth space here. : ) I'm certainly fine with an intro which only mentions relationships of VF to other groups/projects if those relationships involve one or more commitments.

[bhaugen]

@ahdinosaur reminded me about his improved VF Intro. @agentlewis - did that do it better for you?

I love that intro in Mikey's branch, but then I love the intro in master, too. And I love that VF members are starting to branch and fork VF. I had a conversation over the weekend with a visitor to our housing coop in the canyon about protocols not platforms, just to practice how to explain it to not-very-technical people. The way he finally understood it was something like (I paraphrase) "global open [accounting] books that everybody could access and contribute to using anything from apps to email to text messages".

[almereyda]

We have moved the ValueFlows organization from GitHub to https://lab.allmende.io/valueflows.

This issue has been closed here, and all further discussion on this issue can be done at

https://lab.allmende.io/valueflows/forum-valueflo-ws/-/issues/46.

If you have not done so, you are very welcome to register at https://lab.allmende.io and join the ValueFlows organization there.