opengovfoundation / madison

Madison is a platform for lawmakers to share legislation with their citizens, allowing the community to add comments and suggest improvements.

Madison

Madison is an open-source document engagement and feedback platform. While Madison can be used to collaborate on many different kinds of documents, the official version is being built legislative and policy documents in mind.

If you have questions about Madison, please open an issue and we will try to respond as soon as possible.

Check out the Madison Documentation or jump right into the Issue Log for more information on the project.

Architecture

As of 4.0, Madison is a generally plain Laravel (PHP) application.

User Guide

Visit our Engagement Guide for information on using Madison to run engagement rounds.

How to Help

Open an issue, claim an issue, comment on an issue, or submit a pull request to resolve one.

madison's Issues

Test unauthorized annotation creation through API

Refactor V3 files to V4

The following functions are known to be issues:

• flash messages are now using the flash() function
• The Asset class no longer exists

Verification Platform & Process

Add markdown drafting interface to backend

Preferably a lightweight version for now. Will build a more robust version in the future.

Use AngularJS as the front-end app

Integrate H user system with Madison

Add annotator to document pagew

Add POST route for likes / dislikes

Notifications System

Target Outcome #1: A kick-ass notifications system that is the beating heart of the Madison platform, delivering users targeted, fully-personalized alerts to important way-points in the policy development process or when other users interact with them, issues they choose to follow, their generated content, etc.
Target Outcome #2: Complete user control with baked in alert preference selection at every step of the process, from signup to each time a user logs in and navigates throughout the site, passively consuming content or actively contributing it.
Target Outcome #3: Alert delivery across every platform and device commonly used to access the Internet or communicate.

Design Philosophy

Alerts are precious, individual and highly-personal forms of communication. Often, they are the crucial catalyst for action - timely reminders that custom-fit you are what get things done, and provide an indispensable reminder to users who lead busy personal and professional lives. If the alert system isn't righteous, a platform like Madison loses significant utility.

The functionality, durability and personalization of the notifications system should reflect its central importance to the rest of the features and platform. Full user control - at every step of the process - is a must. Each time a user engages with the platform, he or she should be able to choose whether, when and how they would like to be notified with a follow-up nudge. Err on the side of a missed notification versus spamming. Throughout, users are reminded that they control and decide on their own alerts - and that they will be notified of things "outside" of their own alert menu only in very infrequent, very "big deal" circumstances.

Overview
The pillars of the notifications system are answers to these three central questions:

• What is the alert about?
• How is the alert delivered?
• When is the alert delivered?

What is the Alert About?

• A question the user submitted is answered
• A message/comment has been received/read/opened
• A comment or edit is commented or edited by another user
• A comment or edit is upvoted/downvoted (?)
• Another user sends you a message
• A new feature/system update is deployed
• Content is added to the community that, based on a user's other interests, should be of interest.
• A tracked item or issue approaches/is at/moves beyond key policymaking waypoints (votes, hearings, etc)
• A user's contributed content is shared within or outside of the platform via social media, email, etc.
• A comment/suggested is accepted into the policy document by its author
• Content drafted from scratch of which the user is primarily responsible is viewed/supported/commented upon
• Daily/weekly/monthly summaries of the items/issues/activity of each user.
• "Real world" events are scheduled relating to issues/items a user is tracking or working on
• A user's "democracy karma" bank statement

How is the Alert Delivered?

• Text message
• Email
• Twitter (public reply or direct message)
• Facebook message
• Google+ public reply
• LinkedIn message
• Snail mail
• A pop up or alert bar when the user next logs into Madison
• Telephone call (?)
• A calendar alert (e.g. google calendar)

**When is the Alert Delivered?*

• As-it-happens
• Daily summary
• Weekly summary
• Monthly summary
• Daily everything
• Weekly everything
• Monthly everything
• 1 week before key events
• 1 day before key events
• 1 hour before key events

Good Notifications System Examples

• Google groups
• Twitter
• Facebook
• eBay
• Travel alerts
• foursquare (?)

Add WYSIWYG for static page creation

Is this necessary?

Remove Madison comment system

Add markdown parser to reader page

Index documents in elasticsearch

This will allow us to easily add search across documents

Move V3 Files to V4 branch

This includes:

• Public files
• Models
• Views
• Controllers
• Migrations
• Bundles
• Libraries ( application/libraries )
• Routes

imagesloaded.min.js error

This library is included for qtip's responsive positioning. Right now it's causing an error:

Uncaught TypeError: undefined is not a function

on page load.

Create import script for US house style xml

Allow users to reset their password via email

Move user information from hidden inputs to JS user model

Right now Annotator is pulling data from hidden inputs in doc/reader/index.blade.php . Ideally this data is moved to a user front-end model, possible when migrating to angular.

Add h js files to front-end

Merge V4 branch

Test refactored code and merge v4 branch into master

jquery.min.map not found

The jquery migration needs to be included

Use RequireJS to load JS libraries

Add ability for document owners / staff to update bills and meta information

Each change to the document will need to be saved as a git commit to the markdown document

Create granular user levels and document ownership

Store drafts as Markdown documents

Is this best to store as document files or blobs in the database? I'm leaning strongly toward files.

Set 'updated' field in Annotation POST / PUT API routes

Redirect user to the page they were previously on when logging in

This can be done with the Redirect::back() method.

User Registration/Signup Process (Verified User)

Target Outcome #1: Verified users enjoy the same ridiculously efficient, hassle-free and secure sign-up experience as everyday users, with early and clear ways to become a verified user, as well as polite and periodic reminders.
Target Outcome #2: Secure, user-controlled process throughout, with "extra mile" explanations and reminders baked in everywhere. Users who shouldn't seek verification gently weeded - and designed - out at each step.
Target Outcome #3: From the outset, verified users can easily add - and remove - from the conversation as much relevant personal, professional and participatory information as possible, receiving absolute control over their personal information and how they choose to present themselves.
Target Outcome #4: Efficient multi-user authentication, with clear administrative designations and back-end indication of individual user activity on the verified account.
Target Outcome #5: Integration with other verified user platforms as seamless as possible, and encouraged throughout.
Target Outcome #6: Understanding of, and trust in, what it means to be a verified user is engendered from step one of the signup and verification process...and non-verified users don't feel like total schmoes.

Design Philosophy

• No one likes the sign-up process. Particularly verified users, because for them this process often happens a few steps removed from the very information required in secure, efficient and hassle-free authentications. It's a necessary evil, especially because verified users are understood to be signing up in some professional capacity. Our signup process should be made so seamless and surprisingly smooth so that, by comparison, it makes the product stand out from day one - with both the verified user him or herself, or their employee doing all the work.
• Verified user privacy, security and control - of their data, activity and each session - are paramount and persist throughout. Extra sensitivities towards privacy, security and customer support are assuaged from the outset.
• Support, administrative, multi-access accountability are front and center...almost to the point of hand-holding. Instantly, in-line and clearly indicate every form field error, with multiple failures kicking in customer support.
• Eliminate as many form fields as possible at every step, and explain why the additional information is required at every step, with examples if possible.
• Authentication that's fast and secure but not stupidly complex. Guaranteed turn-around times.
• Stands apart from every other verified user signup process, with support kicking in from the first click.
• The more - and more active - verified users, with more complete profiles, the more useful Madison becomes.

Earning their trust, and their business, all starts here.

Initial Sign-Up Form Content (Required)

• First Name
• Last Name
• Email Address
• Create Password
• Confirm Password
• Democracy Points Awarded
• Do You Want to Be A Verified User?

Initial Sign-Up Form Content (Optional)

• Log In With: Facebook, Github, Twitter (?), LinkedIn, Quora (?), Stack Overflow (?), reddit (?), AOL (?), yahoo (?), Foursquare, Google+,
• Complete Your Profile Now or Later?
• Agree to Terms of Use (?)

Verified User Additional Information Form Content (Required)

If the user selects the "verify me" option, they are taken first to a quick splash page or pop-out explaining what a verified user is, what it is not, and what steps must be taken to get verified, and why those steps are necessary. After clicking "got it," the user is taken to this form to fill out this additional information:

• Are you a VIP (like public official), member organization, business or advocacy group? Check boxes or drop-down. If no, they're returned to the everyday user signup process.
• Are you authorized by your organization/boss to be a spokesman?
• Organization/VIP user you represent
• Desired organization username
• Your name (prefilled)
• Your position in the organization/title
• Your email address (prefilled)
• Your LinkedIn profile (optional, but helpful for verification)
• Your boss/supervisor's name
• Your boss/supervisor's title
• Your boss/supervisor's work email address
• Your boss/supervisor's office phone number
• Website URL
• Physical address
• Main hone number
• Links to company/organization/vip social media profiles
• May we follow up with your organization about supporting OpenGov's work?

Once this information is complete, the user is directed to a splash page explaining the verification steps, what to expect from OpenGov, a link to the terms of use they will have to agree to as part of the verification process, and contact information for questions or concerns. Emails containing this exact information are generated to the person who filled out the form, as well as their supervisor. After reviewing and clicking "got it," they're prompted to sign up as a non-verified user themselves and either continue into that process or taken to the main page.

Verification Process

See separate "Issues" on verification features and processes.

Miscellaneous

• "Our Guarantee" made clear throughout sign-up process, and on every profile page(s)

Good Form Design Examples

Smashing Magazine Special Edition on Webform/Signup Process Design (Lots of good articles, from design 101 to eliminating/condensing fields, to validation, etc): http://www.smashingmagazine.com/web-form-design-showcases-and-solutions/

Mobile: https://www.evernote.com/shard/s129/sh/b2613e45-c7bd-460f-9ca3-0cc635bc0e69/d6ee8dfd5db88bc25166600fa3834886

Mint: http://cdns.designmodo.com/wp-content/uploads/2013/01/Mint.com-Sign-Up.jpg

Mint Signup Form Wireframe: http://uxpin.com/uxporn-sign-up.html?seid=370964&img=2013/01/Mint.com-Sign-Up-wireframing-template.png

Github Signup (Clear PW Requirements): http://cdns.designmodo.com/wp-content/uploads/2013/01/GitHub-Sign-Up.jpg

Facebook (Good Design, Suggestion of NEW Password): http://cdns.designmodo.com/wp-content/uploads/2013/01/Facebook-Sign-Up-Form-Wireframe-Template.jpg

Hunch (Encourage Social Sign-Ins): http://cdns.designmodo.com/wp-content/uploads/2013/01/Hunch-Sign-Up.jpg

Tumblr (Great Initial Call to Action in Signup Process): http://cdns.designmodo.com/wp-content/uploads/2013/01/Tumblr-Sign-Up-Form-Wireframe-Template.jpg

Gumroad (Like Tumblr, Gets User "Doing" Wicked Fast): http://discover.usabilla.com/discovery/4f4ca7160a18e7004a000018

Lovely (Keeps Telling User Benefits of Signup All the Way to the End): http://discover.usabilla.com/discovery/4f4ca6fadbe603374d00002a

Mashape (Special Challenges/Requirements for Different Users...In This Case, Developers): http://discover.usabilla.com/discovery/4f4fa0930a18e71d50000080

Verified User Signup Process Overview

• User signs up indicating wish to become a verified user
• User gets quick walk-through of what a verified user is, and is not, and why all that's important.
• User taken to verified user form
• User taken to page explaining the next steps
• User directed to non-verified user sign-up process or back to home page

Add deployments for branches

Modify the Rocketeer config to allow deployments using branches

Document editor needs to expand with preview content

Add authentication to Annotation API

Seed initial migration with admin user

Create admin user on initial migration. Can artisan grab input before the migration to accept the email / pass?

Add front end diffs for different bill milestones

Should be able to toggle diffs against the version before it. In the future you should be able to diff against any tagged version.

Set 'created' field in Annotation POST API route

User Registration/Signup Process (Everyday User)

Target Outcome #1: Users enjoy a ridiculously efficient, hassle-free and secure sign-up experience.
Target Outcome #2: Users can easily add - and remove - from the conversation as much relevant personal, professional and participatory information as possible, receiving absolute control over their personal information and how they choose to present themselves. This includes credential retrieval.
Target Outcome #3: Clear distinctions between verified and everyday users, starting with the sign-up process.

Design Philosophy

• No one likes the sign-up process. It's a necessary evil, but one that can be made so seamless and surprisingly smooth so that, by comparison, it may actually seem a little fun.
• User privacy, security and control - of their data, activity and each session - are paramount and persist throughout.
• Eliminate as many form fields as possible at every step. Authentication that's fast and secure but not stupidly complex.
• Instantly, in-line and clearly indicate every form field error.
• The more complete the profile, the more useful Madison becomes.

Initial Sign-Up Form Content (Required)

• First Name
• Last Name
• Email Address
• Create Password
• Confirm Password
• Democracy Points Awarded

Initial Sign-Up Form Content (Optional)

• Log In With: Facebook, Github, Twitter (?), LinkedIn, Quora (?), Stack Overflow (?), reddit (?), AOL (?), yahoo (?), Foursquare, Google+,
• Complete Your Profile Now or Later?
• Agree to Terms of Use (?)

Miscellaneous

• "Our Guarantee" made clear throughout sign-up process, and on every profile page(s)
• Leave "Do you want to be a verified user?" to later in the process or in a follow-on email/admin-creation

Good Form Design Examples

• Smashing Magazine Special Edition on Webform/Signup Process Design (Lots of good articles, from design 101 to eliminating/condensing fields, to validation, etc): http://www.smashingmagazine.com/web-form-design-showcases-and-solutions/
• Mobile: https://www.evernote.com/shard/s129/sh/b2613e45-c7bd-460f-9ca3-0cc635bc0e69/d6ee8dfd5db88bc25166600fa3834886
• Mint: http://cdns.designmodo.com/wp-content/uploads/2013/01/Mint.com-Sign-Up.jpg
• Mint Signup Form Wireframe: http://uxpin.com/uxporn-sign-up.html?seid=370964&img=2013/01/Mint.com-Sign-Up-wireframing-template.png
• Github Signup (Clear PW Requirements): http://cdns.designmodo.com/wp-content/uploads/2013/01/GitHub-Sign-Up.jpg
• Facebook (Good Design, Suggestion of NEW Password): http://cdns.designmodo.com/wp-content/uploads/2013/01/Facebook-Sign-Up-Form-Wireframe-Template.jpg
• Hunch (Encourage Social Sign-Ins): http://cdns.designmodo.com/wp-content/uploads/2013/01/Hunch-Sign-Up.jpg
• Tumblr (Great Initial Call to Action in Signup Process): http://cdns.designmodo.com/wp-content/uploads/2013/01/Tumblr-Sign-Up-Form-Wireframe-Template.jpg
• Gumroad (Like Tumblr, Gets User "Doing" Wicked Fast): http://discover.usabilla.com/discovery/4f4ca7160a18e7004a000018
• Lovely (Keeps Telling User Benefits of Signup All the Way to the End): http://discover.usabilla.com/discovery/4f4ca6fadbe603374d00002a
• Mashape (Special Challenges/Requirements for Different Users...In This Case, Developers): http://discover.usabilla.com/discovery/4f4fa0930a18e71d50000080

Signup Process Overview

• User signs up
• User taken directly to their home page (including prominent profile progress bar)
• User receives quick and directed tutorial (e.g. new Google products/updates/first-timers)...including a "Got it" option to get right to their user dashboard.
• User receives confirmation email with validation email. Clicking validation takes the user to their profile page with a nudge to complete it the FIRST time only. All other times, user is taken to their dashboard.

Enable profiler in dev environment only

Allow document owners to incorporate user edits into bills

The comments should be marked as some form of resolved, and a git commit made against the markdown document.

Document how to set up Elasticsearch

I found a gist that can help with this:

https://gist.github.com/rajraj/1556657

Create Migration to remove current database schema

Create 404 page

Democracy Karma Bank

Add robust developer / contribution documentation

Add documentation for API

Add hypothesis (h) server

This will likely reside in the vendor directory. Madison needs to check that the backend is running.

Can this be done through a task or should it be done via the BaseController?

Add ability to tag bill stages as 'bill milestones'

Should be done as a git tag that references, for example, when the document was introduced, dropped to the House, etc.

Add import script to admin panel

Add sitemap Route

On the sitemap branch, create sitemap route and add pages / documents. The bundle page is http://bundles.laravel.com/bundle/sitemap which has an example documented.

Add testing suite

Add testing suite / documentation on running

Annotator selector showing up in incorrect location

After selecting a part of a document, the annotator button shows up down and to the right of where it's supposed to.

Incorrect content being loaded for editing

The content included html spans and the badge