Realities Release 0.1 target

Workspaces Software (Participio)
1

It’s now 10 days until we head of to Tunisia to work on Realities! We will be six developers (@hugi, @gustavlrsn, @liam, @questioneer, @owen and @Lazzlo), one facilitator visionary (@brooks) , one artist/designer trickster (@jakobskote) and one PhD in network science and Edgeryder extraordinaire (@alberto). We will be hosted by @Yosser and for the first two days we will be joined by up to seven additional bright and eager local web developers. Furthermore, the great @erikfrisk might be popping in remotely from time to time and we might also get to work with the spectacular @lowlandjuju and @hspeijer.

To harness this power, we need direction. That’s my job, with your help and support, and @brooks above all is helping me keep that direction. As those of you who were around for the first Realities hackathon know, my particular style of setting direction often start with detailed outlines. You also know that these outlines can and should be questioned. Please do so.

Based on feedback, testing and some thinking over the last few months, I’ve come up with a list of improvements that I think we should focus on for our next release. In the spirit of popular open source projects, each release has a code name on a theme, and what is a better theme than Borderland camps? Our first release will be called [re]connect, named after a camp at the Borderland with a particularly good vibe to it. And this project is all about connecting the dots, after all.

So here it is, the direction. Please point out any errors of judgement now. In the coming days I will try to form teams around a bundle of tasks in a way that makes sense.

We won’t necessarily get all this done in Tunisia. Things that still need to be finished can be worked on in December by those who started the work. We have a bit of budget allocated for freelance hours for those who have done significant work already and know the codebase well.

Realities 0.1 – [re]connect

Target release date January 2019

Task summary

Technical core improvements

  • [ ] Realtime data update client side

Authorization

  • [ ] Only allow deletion of Need without Responsibilities

  • [ ] Authorize actions

New features

  • [ ] Multiple deliberation threads

  • [ ] Send email notifications

  • [ ] Reassign Responsibility to other Need

  • [ ] Show user subgraph in profile

  • [ ] Search for people, go to their profile

UX/UI improvements

  • [ ] Guided formatting of Need and Responsibility descriptions

  • [ ] Icons on cards and titles to indicate if realizer vacancy

  • [ ] New entry auto focus on text area

Integrations

  • [ ] Implement Ruby on Rails GraphQL API endpoint in Dreams

  • [ ] Realities connection to Dreams GraphQL API

  • [ ] Realities connection to Loomio (Talk) API

Implementation details

Technical core improvements

Realtime data update client side

When changes are made or Nodes or Responsibilities are added remotely, this must trigger a real time update in the client.

Authorization

Only allow deletion of Need without Responsibilities

Only Needs without linked responsibilities should be deletable. A friendly message explaining this would be nice to have too.

Authorize user actions

  • Authorize: Invite user to take over as Guide

    • Authorized for action:
      • Reality guide for Need or Responsibility

  • Authorize: Invite user to become Realizer

    • Authorized for action:
      • Reality guide for Need or Responsibility
      • Realizer for Need or Responsibility

  • Authorize: Delete node authorization

    • Authorized for action:
      • Reality guide for Need or Responsibility
      • Realizer for Need or Responsibility
      • Only Need without connected Responsibilities can be deleted

  • Authorize: Add and remove dependency authorization

    • Authorized for action:
      • Reality guide for outgoing Need or Responsibility
      • Realizer for outgoing Need or Responsibility

  • Authorize: Reassign Responsibility to other Need

    • Authorized for action:
      • Reality guide for Responsibility
      • Realizer for Responsibility

New features

Multiple deliberation threads

Currently, only a single link to a deliberation thread is allowed per Need or Reality. This is not very useful, since most Needs and Realities will be complicated enough that multiple threads are needed. Instead, we want to be able to define:

  • A group on Loomio/Talk where deliberation usually happens for this thing.
  • Any number of threads on Loomio/Talk where discussion on this thing is happening.

Instead of the deliberation link being a property on the Need or Responsibility Node, it will now become its own (Info) node with a HAS_DELIBERATION relationship to any number of Needs or Responsibilities. Essentially, the thread is information, and the deliberation is defined by the relationship to the node.

To make it clear if there are active discussions ongoing, it should be possible to set the status of a deliberation. To begin with we will have four statuses – Active, Closed, Inactive and Active Conflict. These are set manually. This status is held as a property by the HAS_DELIBERATION relationship.

If a Loomio/Talk group is added, this is automatically sensed and instead of a HAS_DELIBERATION relation, a HAS_DELIBERATION_GROUP relation is created. Groups and threads are distinguished by colour and styling in the UI.

If a Need has a deliberation group, any Responsibility fulfilling that Need automatically gets a HAS_DELIBERATION_GROUP relation to the same (Info) node.

Send email notification

Users need to be notified of changes to things they care about via email. We will send notification in the following cases:

  • When user has been assigned to a role
  • When description or title changes
    • If user is guide or realizer
  • When deliberation thread is added or removed
    • If user is guide or realizer
    • If user is guide or realizer for dependent node
    • If user is guide or realizer of Responsibility or Need
  • When dependency created to what user is guide or realizer for

Reassign Responsibility to other Need

A Guide or Realiser can change which Need a Responsibility fulfils.

Show user subgraph in profile

User profile should show subgraph of current user and a list of Needs and Responsibilities that user is related to.

Search for people and go to their profile

Searching for a user should be possible, and clicking on the user should take you to their profile and show you their subgraph.

UX/UI improvements

Guided formatting of Need and Responsibility descriptions

A Need is always written (We need to … so that … ) and a Responsibility always starts with the Need description, so that “We need to … so that … To do that …”. This should be guided or enforced in the UX/UI, either by pre-filling text or assisting somehow.

Icons on cards and titles to indicate vacancy

Users should be able to see if a Need or Responsibility has a Guide and Realizer assigned without opening the card.

Integrations

Realities connection to Loomio (Talk) API

Loomio has an API that is very easy to access and which can give all publicly available data in JSON format. We can periodically query Loomio for all publicly available groups and threads, to create Info nodes which we can then add create HAS_DELIBERATION and HAS_DELIBERATION_GROUP relations to.

Implement Ruby on Rails GraphQL API endpoint in Dreams

Eventually we want to show information from Realities on Dreams in order to get more people at the Borderland to understand the nuts and bolts that go into creating the conditions for their dreams to come true, and for the to become active participants in those processes. We also want to import all Dreams into the Realities database (but usually not show them) so that each Dream can have it’s own subgraph, and can define what Needs it has and which Responsibilities it depends on.

Ruby on Rails has a very good GraphQL endpoint package, used and maintained by GitHub, Shopify and Kickstarter. By implementing this in Dreams, we make it really easy for Dreams and Realities to talk to one another.

Realities connection to Dreams GraphQL API

Once we have a GraphQL connection to Dreams, we can periodically query Dreams for all public Dreams, Grants and Users and store this data in the Realities database for future development and experimentation.

1 Like
2

For the curious, there are also a ton of future features and improvements that did not make it into this already ambitious release cycle. Here are the things currently in the “parking lot”, expected in future releases.

Realities future releases (not done in Tunisia workweek)

Technical core improvements

  • [ ] Unit testing

Features

  • [ ] Node revision history

    • Description update history
    • Add/remove guide & realizer history
    • Add/remove deliberation thread history
    • Update title history

  • [ ] Add tasks board

    • Link to a Trello board
    • Trello API integration

  • [ ] Add Involved role

    • Allow user to add themselves to list of people ‘involved in’ a Need or Responsibility
    • Add IS_INVOLVED_IN relationship

  • [ ] Show full graph

    • We want to be able to show the entire Realities graph in a large window.

  • [ ] Show subgraph for Dream

    • Allow any user to set dream dependency on Responsibility or Need

UX/UI improvements

  • [ ] Progress bar and guide when creating new node

  • [ ] It’s not clear that the responsibilities list shows responsibilities for the selected need in the needs list. Improve this somehow.

  • [ ] Use graphical representation, and assign an emoji to represent Node

3

This looks very reasonable. One thing I’m missing is an approach to what would be contained in a user profile and the context around it. Assuming that the RGs will mostly be dealing with people they don’t know, its important to have a channel for declaring oneself. A profile would be a good transparent way for someone to highlight their strengths, desires for roles and communication preferences.

1 Like
4

Related to profile information, we should get clever about the information fields on needs and responsibility nodes. I think this requires some deliberation on how much info to anchor to nodes vs edges. It’s probably easier technically to store information in node fields, but maybe there are arguments for storing that information in the relationships between them. Looking forward to getting nerdy about networks with @Alberto. That we’re getting info nodes is something I consider a game changer, and I’m very excited about the potential it opens up for.

5

Nope, there is literally no difference between storing a property in a node or in a relationship. It adds no technical overhead at all. That’s one of the strong suits of a graph database.

6

Awesome summary @hugi!

Here we should probably add:

  • Authenticate: Edit node authorization (title, description, deliberationLink)
    • Authorised for action:
      • Reality guide for Need or Responsibility
      • Realizer for Need or Responsibility

Technically, all the actions here are about authorization, not authentication (yeah, I’m that guy now :stuck_out_tongue:).

Does this mean that deliberationLinks will only be able to go to Loomio? Will we remove the ability for people to link to a Trello, Google Doc, etc. if they want to, or will we still give users an input field where they can put anything, and simply give them some extra powers if it happens to be a Loomio/Talk link?

One thing I think is missing is a refactor/rebuild of how GraphQL resolvers are composed (or not composed, as it the case now) in the back-end. Basically, what I describe here and in the api README in the repo. I think it’s better to do that sooner rather than later.

7

I think its super important that the info node can contain all kinds of links as Realities then also would be able to act not just as a general repository of knowledge, one where the necessary info can be provided and anchored to the roles that need it.

1 Like
8

Another consideration to look at is (probably during the development week) is how the app architecture facilitates disputes. I think it’s well beyond the scope of MVP to provide specialized features that makes various forms of dispute a button push, but it might be worth looking at our MVP and see if there are any features lacking that would result in making such disputes harder to contextual Iz and resolve.

Some example disputes off the top of my head:

  • disputing the realizer or guide to a responsibility, perhaps including a dispute over whether I agreed to take on a responsibility.
  • disputing the scope in time or people asked during an AP
  • disputing the results of an AP if new information has come to light
  • disputing whether a responsibility is necessary
  • disputing the budget assigned to a responsibilty

Experience has shown us that quick and easy escalation of conflict is key to it not getting locked up and defaulting to the undesired resolution through the game of Mule(like the game of Chicken, except the one who wins is the one who loses their fucks to give last)

1 Like
9

I was actually thinking that we would allow that to be changed freely, like in a wiki.
Instead, we’d notify of changes and in the future implement a revision history to be able to restore to earlier versions.

You’re right of course. I’m happy you are that guy, and I’ve changed it.

I think deliberation links should be able to be anything. However, if they are from Loomio/Talk, this should be sensed and the Deliberation node should somehow be represented to show that, and also show if it’s a thread or a group. I guess it would be pretty easy to have three cases here:

  • If deliberation link is not Loomio thread, represent as unclassified Info node
  • If deliberation link is Loomio thread, show thread title and indicate that it’s a thread
  • If deliberation link is group, show group title and allow it to be set as default discussion group, which means that it’s recommended as the place to post things and make decisions on this subject
  • If a default group is set for a Need, perhaps this should be set as the default also for any responsibility created fulfilling that Need? It can then be removed or replaced if it doesn’t fit, but at least there is some indication of where to go to talk.

Of course this adds some logic and code to this feature, but is reasonably straight forward, though it requires us to implement the functions talking to the Loomio API first. What do you think of this @brooks?

This will make for some good dinner discussion!

1 Like
10

Making the distinction between unclassified info nodes and talk deliberation is exactly what I’d want from this. Love it.
I also see this opening up for representation of AP and conflict processes as part of the network.

For example, a conflict about the nature of multiple needs and responsibilities could be represented by a deliberation node with ‘disputed by’, ‘mediated by’, ‘involving’ links.

My heart that beats for complexity flutters. Intuitively I’m starting to see this system attaining the degrees of freedom necessary for the custodians of it to get really creative with it!

1 Like
11

Here’s another feature that just became clear to me as a need: Dashboards. Perhaps not a 0.1 feature, but on the other hand it could be that this could be developed in parallel by developers who aren’t deep enough in the stack.

Let’s face it: the UX isn’t exactly Facebook. It’s not going to be immediately intuitive for most users how to use it, and getting it to a point where it is easy and requires no training isn’t anywhere close. This is one reason I’ll be working to assemble the Reality Guides to function as curators of the platform and facilitators of the people doing the work.

But perhaps an easy way to visualize the information users need to work could be to create dashboards that contextualize the information contained in the graph around a given node.

What I’m thinking are web pages generated by making queries to the database and parsing them into natural language. I can give examples of this if it isn’t clear enough.

12

We are now at the hackathon in Medenine, and are about to start working on tasks above.
Three teams will work on three tasks. We will not work on all tasks during these two days. These are the tasks we focus on now, in three teams:

  1. Team graph visualisation: Show user subgraph in profile
  2. Team email: Send email notification team
  3. Team deliberation: Multiple deliberation threads team

Teams will work on branches. Once done, we will make a pull request which will be reviewed before it is merged into the master branch.

2 Likes