Councilmatic Documentation

Councilmatic Documentation

Motivation and Overview

I want to be able to follow primary source material on legislation as it develops in my city. I also want to have appropraite contet around this legislation so that I can develop my own better informed opinions. Having this ability makes me feel as though I can actually be involved in the process of guiding the city -- it opens the black box of how things are done, and makes legislation accessible outside of its consequences.

There are three aspects here:

• subscription,
• contextualization, and
• evaluation (pros and cons)

Subscription: I want to be able to subscribe to legislation as its made available, and to agendas of what's going to be discussed in the future. Councilmatic will provide email, RSS, or SMS subscriptions to headlines that you desire. It will also present updates to your subscribed information in a way that is optimized for your viewing mode, be it web or mobile.

Contextualization: I want to see relevant information around legislation, like mentioned areas, supporting areas (with councilember as proxy), related legislation, and related information from around the internet. Councilmatic will collect meta-information on legislation such as the words in a bill, and the other bills that it refers to (determined through regular expression analysis). It will also allow users to note areas of the city mentioned in legislation.

Evaluation: I want to see the pros and cons of an issue as discussed by the wider community. Councilmatic will allow users to not only comment on a bill, but also specify whether their comment is is support of or opposition to the bill. Other users will be able to comments according to their helpfulness. Through this system will emerge a set of most helpful supportive and opposing viewpoints on the issues in a bill.

Development

Testing

Write tests. Unit and integration tests. Think about them. They should describe the behavior. Tests are not documentation, but the names of the modules, classes, and methods should read like documentation (if you strip out all the "test" prefixes). Something like:

councilmatic/
    subscription/
        tests.py

Contains:

from django.test import TestCase

class Test_SubscriptionDispatcher_send (TestCase):
    def test_sends_subscription_data_to_users_in_their_preferred_format(self):
        ...

The test function names should be descriptive of the test's behavior. It can be long, shouldn't have to be too long, because each test should test limited behavior. long, because each test should test limited behavior.

System Behavior

Below are fairly technical notes of what goes on in Councilmatic.

What happens when you create an account

When a new account is created, a signal is fired on the auth.User model. The subscriptions app listens for this signal, and creates a bookmarked content subscription for the user.