end of colins first draft of usage visual data welcome

Author: colinmegill

SUMMARY.md

@@ -12,6 +12,7 @@
    * [User Authorization](usage/UserAuthorization.md)
    * [Embedding](usage/Embedding.md)
    * [Per User Config](usage/PerUserConfig.md)
+   * [Events](usage/Events.md)
    * [Configuration Templates](usage/ConfigurationTemplates.md)
    * [Best Practices](usage/BestPractices.md)
 * [Visualization](visualization/README.md)

data/Analytics.md

@@ -1,6 +1,6 @@
 # Conversation Analytics
 
-The graphs below are from a real polis conversation and illustrate an important point. Polis engages [lurkers](https://en.wikipedia.org/wiki/Lurker) - users who don't engage if their sole option is to write a comment. 
+The graphs below are from a real polis conversation and illustrate an important point. Polis engages [lurkers](https://en.wikipedia.org/wiki/Lurker) - users who don't engage if their sole option is to write a comment.
 
 ## Number of unique hits, voters, and comment authors over time
 ------------
@@ -10,29 +10,28 @@ This graph shows participation rates across three segments:
 * Users who wrote and submitted a comment
 * Users who clicked agree and disagree at least once
 
-~1% of users commented. ~25% of users voted. 
+~1% of users commented. ~25% of users voted.
 
 ![Hits, Voters, Comment Authors Image](../hitsVotersCommenters.jpg)
 
 
-
 ## Votes per participant
 --------------------
-The graph above begs a question: of those who voted, how much did they vote? The next graph gives us insight in to that. People vote a lot! 
+The graph above begs a question: of those who voted, how much did they vote? The next graph gives us insight in to that. People vote a lot!
 
 The light gray bars denote users who voted less than 7 times. These users are not included in the statistical computation or the visualization, because of a lack of data for them.
 
 ![Votes per participant image](../votesXPtpt.png)
 
 
-## Number of votes over time 
+## Number of votes over time
 ------------------
 
 How many votes were cast, and when?
 
 ![Votes over time image](../Votes.jpg)
 
-## Comments over time 
+## Comments over time
 ------------
 How does that compare to the number of comments submitted? In this conversation, there were ~250x more votes than comments!
 

data/Export.md

@@ -1 +1,3 @@
-Yes. [chris to fill in, in excruciating detail]
+# Data Export
+
+[chris to fill in, in detail]

data/HowToUse.md

@@ -1,6 +1,6 @@
 Using Polis data
 
-
+[Chris to fill in]
 
 One of the most powerful things you can do with polis data is to correlate it with data you already have about your users. For instance, if there are 4 groups, try correlating the members of each group with gender, length of employment, geographic distribution, etc.
 

data/WhatWeCollect.md

@@ -1,3 +1,5 @@
 Data
 
+[Chris to fill in]
+
 Polis generates groups of people correlated with comments they tended to agree on. It also produces comments with numbers of agrees and disagrees. You can also export the entire votes matrix of every person by every comment.

usage/BestPractices.md

@@ -1 +1,11 @@
-Do seed some comments, don't add too many comments. Is there a ratio? Power curve?
+# Best Practices
+
+* Add seed comments. Add obvious, diverse perspectives to give groups initial structure
+* Don't let the number of comments get too high (a few hundred is a lot)
+* Moderate in the best example of each point - moderate out reptition
+* Comments submitted after most participants have already voted will be under represented. Try to:
+  * Encourage participants to stop back a few times to vote on new comments
+  * Disallow new comments towards the end
+* Use strict moderation, and moderate as soon as you see new comments (we will email you)
+* If appropriate, add some key identifying statements such as "I have completed university."
+

usage/CommentModeration.md

@@ -1,19 +1,23 @@
 # Moderation
 
-Strict mode: which means that no comments go out unless you have approved them to be shown. 
+Strict mode: which means that no comments go out unless you have approved them to be shown.
 
-Lazy mode: all comments go out and you can hide a comment after-the-fact. 
+Lazy mode: all comments go out and you can hide a comment after-the-fact.
 
 Polis has a built-in profanity filter you can toggle on and off. The profanity filter will automatically moderate out comments that contain profanity.
 
 To moderate comments:
 
 `pol.is/m/55555 >> Comments >> TODO`
 
+Note that rejected comments cannot be moderated back into the conversation, but that you can copy and paste it back in as a seed comment.
+
 To turn on / off strict moderation:
 
 `pol.is/m/55555 >> Config >> Strict Moderation`
 
-To turn on / off profanity filter: 
+To turn on / off profanity filter:
+
+`pol.is/m/55555 >> Config >> Profanity Filter`
 
-`pol.is/m/55555 >> Config >> Profanity Filter`
+#### Meta Moderation (on react dashboard across all conversations)

usage/ConfigurationTemplates.md

@@ -1 +1,5 @@
-Right now, you have to do this manually every time. Templates are due in a future release of polis to make this process easier.
+# Templates
+
+Coming soon!
+
+Templates will reduce the pain of per-user config across multiple conversations.

usage/Embedding.md

@@ -1,14 +1,21 @@
-Using polis on your site is as easy as dropping in a script tag. The biggest consideration is whether you want to use polis in a template system like Wordpress across your entire site, in which polis creates the conversations automatically based on the URL of the page they are embedded on, or drop it in here and there and create each conversation manually.
+# Embedding
 
-Creating each conversation manually:
+You can embed polis on your site or in your app the way you would a YouTube video or a comment system. The process is simple: add a script tag which loads an `<iframe/>` asynchronously.
 
-If you're going to create each conversation manually, click +new from the inbox and add your topic and description. Then grab the script tag and put it wherever you like on your site.
+There are two options: manually creating embedded conversations or having Polis create them automatically in your templates.
 
-Creating conversations automatically:
+#### Creating each conversation manually:
 
-Copy and paste this into the template for your pages (blog posts, news articles, etc)
+1. In the [inbox](https://pol.is/inbox), click [+new](https://pol.is/conversation/create)
+2. Give your conversation a topic and description (*default none*)
+3. Decide what flavor of [moderation](usage/CommentModeration.md) you'd like, lazy or strict (*default lazy*)
+4. Click create
+5. Copy out the script tag
+6. Paste it into the HTML of your site where you'd like the `<iframe/>` to appear.
 
-When this embed code loads on your website, it will either create a new conversation (if one doesn't already exist) or load an existing conversation. It keeps track of what conversations belongs on what pages via the data-page_id HTML attribute. Simply replace "PAGE_ID", either manually or in your templates, to create new conversations and load existing ones in the right place.
+#### Creating conversations automatically:
+
+Copy and paste this into a template (blog posts, news articles, etc).
 
 ```
 <div
@@ -18,3 +25,6 @@ When this embed code loads on your website, it will either create a new conversa
 </div>
 <script async="true" src="https://pol.is/embed.js"></script>
 ```
+
+When this embed code loads, it will either create a new conversation (if one doesn't already exist) or load an existing conversation. Your job is to replace `PAGE_ID` in your template. `PAGE_ID` is the lookup Polis uses to keep track of what conversations belongs on what page.
+

usage/Events.md

@@ -0,0 +1,15 @@
+# Events
+
+The Polis embed code and `<iframe/>` are configured to emit a "vote" event each time a participant votes.
+You can subscribe to those events on the page that instantiates the `<iframe/>` like this:
+
+```
+ window.addEventListener("message", function(event) {
+  var data = event.data||{};
+  if (!event.origin.match(/pol.is$/)) {
+    return;
+  }
+  if (data.name === "vote") {
+    alert("vote!");
+  }
+```

usage/PerUserConfig.md

@@ -1,7 +1,17 @@
+# Per User Config
+
+Each time Polis loads into an embedded context, you can *optionally* configure Polis at the user level to hide or show facets of the interface.
+
+#### Hiding the comment submit form
+
 The data-ucw (user can write) tag toggles writing, and is only relevant for that user for that session.
 
+#### Hiding voting interface
+
 The data-ucv (user can vote) tag toggles voting, and is only relevant for that user for that session.
 
+#### Hiding the visualization
+
 The data-show_vis causes the vis to be enabled or disabled when the conversation initializes. This is a one-time setting which is picked up and stored in our db the first time someone loads this script. If you later change this value, it won't have any effect. To change that value, you can load the config tab of the admin page for that conversation (the button for the conversation's admin page should appear in preprod.pol.is/inbox )
 
 ```
@@ -16,18 +26,3 @@ The data-show_vis causes the vis to be enabled or disabled when the conversation
 </div>
 <script async="true" src="https://preprod.pol.is/embed.js"></script>
 ```
-
-Also, I added code to emit a "vote" event each time a participant votes.
-You can subscribe to that like this:
-
-```
- window.addEventListener("message", function(event) {
-      var data = event.data||{};
-      if (!event.origin.match(/pol.is$/)) {
-        return;
-      }
-      if (data.name === "vote") {
-        alert("vote!");
-      }
-    });
-```

usage/UserAuthorization.md

@@ -1,30 +1,53 @@
 # User Authorization
 
-Sometimes it doesn't matter if you know who is who. Sometimes it doesn't matter, but you want to make sure people aren't voting again and again to game the system. Sometimes you want transparency. Maybe you already know who they are. Maybe you have your own authorization system. 
+Sometimes it doesn't matter if you know who is who in a Polis conversation. Sometimes it doesn't matter, but you want to make sure people aren't voting again and again to game the system. Sometimes you want transparency. Maybe you already know who your users are. Maybe you have your own authorization system.
 
 Polis handles all these cases. Here's how.
 
 #### Optional social login
 
-*DEFAULT* 
+*DEFAULT*
 
-By default
+By default, participants can write and vote anonymously, but are prompted to sign in using Facbeook and Twitter. This is low friction for users and encourages voting and writing.
 
+#### Social login required to write
 
+`pol.is/m/55555 >> Config >> User login required to write >> ON`
 
+#### Social login required to vote
 
+`pol.is/m/55555 >> Config >> User login required to vote >> ON`
 
-There are multiple options for authorizing your participants. By default, users are prompted to connect to write and vote but do not have to. This is low friction usage and encourages activity in your conversations. Here are some other options:
+#### Social login prompts disabled
 
-Completely Anonymous - turn off social
+In this scenario, users who have already validated a social profile will still be shown. No users will be prompted to connect their social profile
 
-Anon but verified
+`pol.is/m/55555 >> Config >> User shown social login >> OFF`
 
-Social login to write
+#### Completely Anonymous
 
-Social login to vote
+In this scenario, even users who have already validated a social profile will not be shown. The visualization is hidden.
 
-Social login to write & vote
+`pol.is/m/55555 >> Config >> Total Anonymity for All Users >> ON`
 
-xid (is this the same as the data-yoursitecreds that we will do for times)
+#### Anonymous but verified via social account login
 
+In this scenario, all users are prompted to connect social before voting and / or writing, but the visualization is hidden and no users identities are passed on to you as the owner. This scenario is ideal if you need to ensure that users are not gaming the system, and possibly collect metadata from the accounts like a restricted geolocation, but ensure that identities remain secret.
+
+`pol.is/m/55555 >> Config >> Anonymous but verified with social account >> ON`
+
+#### Proprietary auth
+
+This scenario is only available if the Polis conversation is instantitaed through an embedded `<iframe/>` on your page. You'll decide whether or not the user is verified. You can then use the [per user config] data attributes to customize the experience at will. A nice pattern is to shut off writing and voting for those not logged in, so that users who are not logged in can still consume a read-only version of the conversation by clicking through the visualization.
+
+`data-user-image-url=""`
+
+#### Creating custom URLs for each participant to join
+
+Let's say you are a business intelligence analyst, and a hospital has hired you to run a survey of its doctors and nurses. Conveniently for the purposes of our example, they've asked you to use Polis.
+
+In this scenario, the hospital has an employee database. They would like to correlate employment data - columns like role, length of employment, age, gender, etc. - with groups that emerge in Polis. You are going to send out pol.is links, but it's not appropriate to have doctors and nurses connect
+
+In this case, you'll want to create a URL per participant, with a key that you can use to map them back to the data you already have about them.
+
+...

visualization/HowToRead.md

@@ -1,3 +1,26 @@
-Visualization is showing groups of participants that voted similarly across a range of issues. People do not form groups in polis because of just one issue they form groups because they voted similarly on many issues.
+# How to read the visualization
 
-When you click on a group you are seeing comments that a majority of people in that group voted the same way on, in a carousel.
+The visualization in Polis has three purposes:
+
+1. **Engagement** - To show a user how his or her opinions relate to everyone else's
+2. **Education** - To instruct the user what dimensions are already under consideration before he or she writes
+3. **Insight** - To reveal the landscape of opinion (minority, majority, consensus)
+
+#### Individuals
+
+* Every participant is positioned closest to other participants that voted similarly
+* Every participant sees their own position as a circle with a blue halo around it
+* Clicking an individual brings you to their social profile, with a preference for Twitter
+
+#### Groups
+
+* Groups of participants have a dotted line around them - these groups can be clicked on
+* Groups form because members voted similarly on multiple issues, not just one issue
+
+When you click on a group, a carousel of comments will appear. These comments that tended to differentiate the group from other groups. Specifically, these are comments that people *inside* the group voted similarly on, while people *outside* the group voted differently on.
+
+As you swipe through the carousel, you will see the visualization change. Each person assumes a green, red or grey halo, depending on whether they agreed, disagreed or passed on the comment presently in the carousel.
+
+The circle in the middle of each group has two components.
+1. The number in the center is the number of people in the group total (including those who are in the visualization).
+2. When a group (or majority opinion) is selected, the halo shows the ratio of agrees, disagrees and passes in the group *for only those participants who saw the comment*. The carousel has a percentage of participants in a given group who agreed or disagreed with a comment, and that number also reflects *only those participants in the group who saw the comment*.

visualization/TheMath.md

@@ -1,8 +1,7 @@
-
-If you want to go deeper on the math behind the visualization, check out this blog post. The short story is that we’re doing principle components analysis on a sparse matrix of people by comments, then k means clustering where k is between 2 and 5.
+# The Math
 
 You've probably seen 'recommended products' on Amazon, or 'recommended movies' on Netflix. Each of those services uses statistics to group you with people who buy and watch similar things, then show you things that those people bought or watched.
 
 When you cast a vote on a comment, you are grouped with people who voted like you did! You can see those groups below. Each is made up of people who have similar opinions. There are fascinating insights to discover in each conversation. Go ahead - click a group to see what brought them together and what makes them unique.
 
-
+[Chris may add more here]

visualization/WhoGetsShown.md

@@ -1,8 +1,13 @@
-Visualization: who gets shown
+# Who gets shown?
 
-The visualization is potentially different for every user. There is a hierarchy of who get shown in the visualization. First we show a user's Facebook friends provided that you have connected to Facebook. After that we should people with a verified twitter accounts, then the people with the highest Twitter follower Count, and after that we fill in with random accounts from Facebook.
+The visualization is potentially different for every user. There is a hierarchy of who get shown. Our algorithm follows the following priority:
 
-You can override this by featuring certain users in the admin panel, filtering people the same when you filter comments.
+1. Featured (if you've featured any participants)
+2. Facebook friends (provided the participant has connected Facebook)
+3. Participants with verified Twitter accounts
+4. Participants with the most Twitter followers
+5. Random Facebook accounts
 
-pol.is/m/5555555555 >> People >> Default
+The first priority are users you have decided to feature. To feature / remove users:
 
+`pol.is/m/5555555555 >> People >> Default`

welcome/Motivation.md

@@ -1,12 +1,24 @@
 # Motivation
 
-Comments suck. Surveys suck. Here's the deeper story behind the creation of polis.
+Polis was conceived during the Arab Spring and Occupy Wall Street. Both movements were decentralized and emergent. Twitter and Facebook proved instrumental in, mobilizing citizens, garnering media attention and disseminating information. They were not successful at producing coherence.
+
+#### Coherence Without Centrality
+
+The problems faced by the protestors in both cases are just an exaggerated, extreme form of the problem every organization over a few hundred people faces. There is a wonderful quote by Michel Foucault that captures it:
+
+People know what they do
+People frequently know why they do what they do
+But no one knows what what they do does
+
+This is the essence of
+
+Smart policy is policy instructed by many quarters
+
 
-Polis was conceived during the Green Revolution in Iran, the Arab Spring, and Occupy Wall Street. These years, 2009-2011, showed the promise of digital democracy. They also bore out many of its shortcomings.
 
 Lorem ipsummm...
 
 * help crowds speak with one voice without centralizing power in an individual
-* 
+*
 
 polarization

welcome/Quickstart.md

@@ -9,5 +9,5 @@ You can have your first Polis conversation up and tweeted in less than a minute.
 5. Click create
 6. Paste the share link (it will look something like pol.is/55555) into an email, a tweet, etc.
 7. Go to your conversation, watch responses roll in, etc.
-8. **Important**: if you selected strict moderation mode (no comments shown without approval) make sure to moderate comments into the conversation! If you conversation is pol.is/55555, your admin console can be found at pol.is/**m**/55555. 
+8. **Important**: if you selected strict moderation mode (no comments shown without approval) make sure to moderate comments into the conversation! If you conversation is pol.is/55555, your admin console can be found at pol.is/**m**/55555.