User Panels

[wbt]

Issue #124 proposes allowing people to record their positions on a bill beyond emoji. The emoji module on each bill currently shows an aggregated count of how many people have reacted to a given bill with each emoji. This is not necessarily representative and easy to game. Especially when combined with the challenge of figuring out the meaning of some emoji in the context of some bills, this limits the useful interpretability of the emoji aggregates. The functionality proposed for #124, which I hope to contribute, is good for individual note-taking. In the present issue, I propose a mechanism for assigning users to panels, which can be assembled in such a way that the aggregate is meaningful.

Here is a conceptual list of some new data fields that appear needed, in addition to ids for new tables:

Auth_permission (additional permission):
[can_]create_panels (at least at first, we might not want to allow every user to create and manage panels)

User:
Consider adding a user_emails table allowing any one account to be associated with multiple e-mail addresses. That should probably be tracked in a separate Issue.

Panel:
title
description (which may include text about how the panel administrator will use/share the data)
shows_individual_positions (Boolean)

Panel_join_code:
panel_id
code
start_datetime
end_datetime (can be null)

Panel_permission: a many-to-many join between users and panels, with additional information
user_id
panel_id
permission (enum, e.g. view_members, edit_members, view_positions, may_join [was invited], contribute_to_aggregate [full member/accepted invitation],…)
code_used (?)
lastmodified (datetime)

Panel_invitation:
panel_permission_id
invitation_sent (datetime)

A user may be on multiple panels simultaneously, and may have different roles on different panels. Many users may be on the same panel together (that is the main point). A view is provided so a user can see what panels they are already on, which ones they have been invited to but not yet accepted, and which ones they have hidden the invitations for, and allows them to move panels between those statuses. This page would also have a box permitting entry of a code to join a panel by code (see below).

A view is needed to show the panel administrator (more precisely, anyone with the view_members or edit_members permission) the list of members of the panel, and their permissions. If the viewer has the edit_members permission, they can do things like:
• invite a new member to join the panel
• delete panel members
• change member permissions
• resend invitations

A possible functional flow might go like this:
A user with the can_create_panels privilege visits GovTrack, and clicks somewhere to Create a new panel. They enter the list of members’ e-mail addresses and invitation e-mails are sent.

If an e-mail address is NOT associated with an existing GovTrack account, instructions indicating a way to create an account or add an e-mail address to an existing account are provided in the e-mail. If a newly registering user already has a panel invitation pending, they are informed about this on joining and offered the chance to accept.

If the e-mail address IS associated with an existing GovTrack account, and the user visits GovTrack (logged in), they might receive a notification pointing them to the page that shows the panel invitation, in addition to the e-mail. The panel invitation explains that joining the panel means that their position on a bill and the reasons they entered for it will be visible to the (named) panel administrator and anyone s/he chooses to share that information with (as may be explained in the panel descriptive text, included in the notification message).

Alternatively, the panel administrator could get a randomly generated code (string) and transmit that to people out-of-band, with instructions to log in to GovTrack and go to the panels page and enter the code. This strategy might increase usability at the cost of potentially decreasing representativeness of the panel. The date-of-validity fields associated with the join code would need to be checked and paired with an interface to invalidate a panel’s current code and optionally change to a new one. If this doesn’t get implemented initially, that’s probably OK.

A view is needed to show the panel administrator (more precisely, anyone with the view_positions permission) the aggregate positions of the members of the panel. This view might include aggregations like:
• Distribution of positions (how many are at each level of support/opposition)
• Free-text comments from users, grouped by their numeric position.

If the shows_individual_positions flag is set, the panel administrator can also see a view listing each user’s invited e-mail address, support/oppose position, and reasons. Otherwise, only the aggregate views are accessible. Again, if this limitation doesn’t get implemented initially, that’s probably OK. Limiting the view to aggregates would probably require checking for a minimum number of active participants in the panel.

This functionality should be written in an extensible way so that in the future, within-panel analyses can be done slicing & dicing the panel by user demographics. Another possible extension that may be good to have in mind when making technical design decisions is the future possibility of sub-panels, assembled by the panel administrator as a subset of a larger panel, but not requiring separate confirmation from the user.

This is intended as a starting post for discussion and could be used to start technical work.

[wbt]

I am making this commit public as a first step towards addressing Issue #124 so that development on the Panels can proceed in parallel and use the same data model.

[JoshData]

Let's break this down to what's essential and what isn't essential. I'm not saying we can't do the non-essential things, but let's focus on what's essential first and return to the non-essential things after the essential things are working.

Essential:

• Auth_Permission for creating panels
• Panel
• PanelInvitation (panel, join_code, send_by_user, creation date) - combines your panel join code and panel invitation
• PanelMembership (panel, user, permission, from_invitation) - your Panel_permission
• A view to create panels, manage membership, see panel data, and export panel data.
• A view for users to accept invitations emailed to them.
• EDIT: Also, any disclaimers/warnings for users in panels in appropriate places about who their info is being shared with.

Maybe not essential:

• Sending invitations through the site. Out-of-band invitations instead would make it easier for the panel admin to customize the email and provide help to invited users.

Not essential:

• user_emails
• associating invitations to existing GovTrack accounts (in which case, showing users which panels they have been invited to but not yet accepted, and hiding invitations, would not make sense if the invitation cannot be associated with an account)
• resend invitations - can be done simply by inviting from scratch
• Panels that can only see aggregates. When a user accepts an invitation, they will simply be warned that some of their data will be visible to the panel owner.
• Data analysis. This can be done instead by exporting the data from GovTrack and then performing analysis in another application.