• Stars
    star
    188
  • Rank 205,563 (Top 5 %)
  • Language
    Ruby
  • License
    BSD 3-Clause "New...
  • Created almost 12 years ago
  • Updated over 3 years ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

common patterns and anti-patterns for civic tech and civic apps

Civic Tech Patterns

In the spirit of Wikipatterns, this is a collection of patterns and anti-patterns for describing common practices that may help or hinder the conception or design of your civic technology.

  1. Design Patterns
  2. Idea Patterns
  3. Design Anti-Patterns
  4. Idea Anti-Patterns
  5. Types of Civic Applications

Usage and Contributions

To discuss any of these, please open an issue, or fork and submit a pull-request.

Design Patterns

Civic Wayfinding

Focus on clearly/accessibly explaining a process and offering a clear "now what" action step. Show people where to put their logical or emotional response: write their reps, letter to the editor, send story to local blog, etc. Instead of trying bulldoze through the walls of bureaucracy, hold people's hand in going up, over, or around them. Take them on a bear hunt:

We're going on a bear hunt, We're gonna catch a big one, What a beautiful day, We're not scared. Oh oh! A river, A deep, cold river. We can't go over it, We can't go under it, We've gotta go through it! Splish splosh, splish splosh.

Go to the People

Engage with people in the places they already go online: Facebook (FACEBOOK!), community blogs/forums or existing services (Foursquare, Twitter, etc.) rather than trying to get them to transfer their activities to your new platform. This could include: Facebook or blog widgets; bookmarklets or browser extensions; embeddable content; or messaging services (Twitter, instant messenger, etc.). This can work hand in hand with the It Alerts You pattern.

It Alerts You

Actively reach out to people when an action has taken place or further action is needed; don't expect them to frequently visit your website or open your application. Optimize your email messages for openings/click-throughs or utilize other messaging services (heck, even the postal service!).

  • Examples: CivicsGarden tweets at you when your plant needs watering or has died.

For Official Adoption

Design your app to be officially adopted or replace an existing resource. You may need to invest more time in social processes (explaining, building trust, gaining buy-in) than engineering; or engineering may need to be focused on maintainance/infrastructure constraints or accessibility (508 compliance!) over raw functionality.

Idea Patterns

Reimagine

Engage people in creative, curious or inane thought. Be unlike the "typical" experience or style of engagement with a topic or problem. One potential danger to this pattern is the lack of a clear action step.

Do your research

Research common questions or phrases that people are googling within a topic/issue-area. Look at the top resulting links and build an app that is both subjectively better than the competition and has a chance of having a higher Google ranking. Google even has a keyword research tool.

Self-tested

Build an application that you yourself fully and/or regularly use. Assuming you aren't a sociopath, though admitting that you aren't representative of everyone or even many-one, building something that is insanely useful to you can result in something that is relevant to others. Unfortunately, it's often easy to fall into the subsequent anti-pattern,

Seek Out Existing Communities

Find an existing community (online, offline, geographical, affinity, etc.) to discover problems, pain points and potential interventions. You get an automatic userbase with a shared identity who--assuming you're a good listener---already understand the problem your technical intervention is trying to solve. Beware of potential Idea Anti-Patterns such as Intention Over Practice, Management Problems or Niche Tools.

Digitize a Process

Build a tool that makes an existing process easier, faster, better, stronger. Ask, "is someone already doing this, but on paper or by phone?" At the same time, be aware that simply digitizing a process can take valuable social interactions out of what seems like an inefficient process. (See also: Seek Out Existing Communities)

Make it Mobile

Take information in a closed format and make it available to people when and where they need it. Today, that often means on a smartphone (which people do have -- see Go to the People, above, and ...and it has SMS, an anti-pattern)

Relevance

Is the app doing something that matters to people in the field? For example, is it tracking things that matter to the people who are tracking them? Are you only tracking stuff that only matters to management?

Have A Business Model

Even as a thought experiment, asking โ€œwho would pay money for this and how much?โ€ can crystallize intent. It'll help you find your audience and your value.

Bridging tech capacity

Is it doing something that the people who should make it cannot do for time, money, skill reasons? Maybe they already have tech capacity to do 90% of stuff, but just need help getting data out of the system, etc.

Content before Engineering

Can you explain a process so that people really understand it well before you build the system to contain the process? Are you an expert in that process and have actually experienced it? See "It's For the little people"

A Happening

An impermanent experience can be more transformative than a permanent artifact. Build a brief or one-off experience that someone (or a group of people) can go through and be done without any future expectations or collateral. Just because computers are really good at storing stuff doesn't mean you have to capitulate to their silicon whims. May be a subset of the Reimagine pattern.

Design Anti-Patterns

Anti-patterns aren't inherently bad. The are often difficult to achieve because their success relies heavily on non-tech stuff like community outreach, content creation and community management. Or, they might just be easy to implement badly. Think twice about adopting one of these patterns.

Civic CMS

"I need a site that has a neighborhood community calendar and a social network and a blog and a map and..." The boringest interaction model ever. These sites often end up abandoned: blogs with no posts for months, empty calendars, and spam-filled comments. Before starting one, ask "Who's going to update it regularly?" and "Why will someone read it?" Instead, consider starting a Facebook page, mailing list, Google calendar, or Twitter feed -- see the Go to the People pattern, above.

A civic CMS might just be what you need if you already have an active online community that wants to take another step. For example, if your neighbors already all read your blog for events, but you want to make it easy for them to add their own, a CMS could be the solution. Just be wary of trying to do it all at once.

โ€œLiberty cannot be established without content, nor content without content moderation.โ€
โ€“ de Tocqueville

..and it has SMS

We all know SMS is code for those people. If your conception of the experience of poverty, economic or social marginalization is "doesn't own smartphone", your app isn't serving real needs or context.

Remove humans from the process

The anti-pattern of Digitize a Process, above. Sometimes, taking a process online cuts efficiency or removes valuable human communication from the mix. For example, in Close to the Machine, Ellen Ullman describes an electronic social services system that lead to less communication between service providers who once traded details with each other by phone.

Games that aren't actually games

Zynga-style "badge acquisition" isn't actually "funโ€ despite being a โ€œgameโ€, it's just addictive. And it usually isn't even addictive -- no one will want to earn badges for shoveling their sidewalk, unless it ties into a larger system that people are already using (see Go to the People, above.)

"Imagine a million usersโ€ฆ"

No, imagine one user (hopefully you); what's the immediate benefit to user #2?

They'll find it via Google / if we build it they will come

Nope. They wonโ€™t.

And then they will tell their friends

Nope. They wonโ€™t do that either, especially if "they" never came in the first place (see "if we built it they will come").

Idea Anti-Patterns

Focus on the negative

Crime maps, restaurant inspections, waste/fraud/abuse. While these may be useful applications, they are overrepresented in civic technology. Also, these applications often do little to challenge people's preconcieved notions, let alone educate them on the process, policies and politics that generated the underlying data in the first place.

Simplify the Complex

This anti-pattern describes the boiling down of a complex, nuanced or difficult-to-understood process/dataset into a simplistic analysis or kneejerk action-step. Often combined with Focus on the Negative.

  • Example: (nearly) all crime maps ever.

Correlation = Causation

Just because you can show crime rates on the same map as all the liquor licenses in your city doesn't mean you should. Correlation doesn't equal causation, and unless you have a good story to tell along with your data visualization, don't lead people astray.

Stuff on a map

Put a bird on it and call it a day. Ask, instead, "what value does a map give?" A list, chart, or just plain text might be much more useful for your readers.

โ€œItโ€™s interestingโ€ / Pseudo Investigative Journalism

Publish with purpose. Don't simply move a public dataset online because it exists. Don't be that newspaper that published the home addresses of gun owners "just because." The exception is if you're doing it as an exercise in learning a technology, which is cool.

The Dead End

If it doesnโ€™t have an action step, so what? In some cases, it's fine if a page is a dead-end. But you probably brought the user to the page for a reason.

Niche tools

From ReportingOn's farewell blogpost about building highly specialized tools for journalists (and applicable to just about any domain, like civic tech):

Unless what you're building meets a very journalism-specific need, you're probably grinding your gears to build something "for journalists" when they just need a great communication tool, independent of any particular niche or category of users.

Management Problems

Ok, so you now you have a great user roles, permissions and auditing system; how does that make it easier for the people actually accessing and entering data into the system?

No competition scan

Make sure you know what's already been done. Where do you fit? Where can you add value? Are the existing sites good enough? There are plenty of untapped opportunities -- it might be better to start there. Then again, you do want to Seek Out Existing Communities.

Intention over Practice

You might be tempted to build something that people want to do (or feel like they should do), but ultimately don't.

  • Examples: The post-conference social network that seems like a great idea at the conference, but subsequently goes unused. The Project/Task Management tool that people would rather agonize over rather than actually doing the project or the task itself

It's Not for Me

Not something the user wants to do, but something you want the user to do You want people to collaborate better, but do they want to collaborate better, or more importantly, are they willing to invest in the collaboration

It's in the algorithm / it's an engineering problem

The problem you see -- perhaps one of crushing bureaucratic incompetence or disorganized citizens -- probably can't be fixed with a website. That said, a digital tool might be designed For Official Adoption.

Theyโ€™ll visit it all the time

Apps on my home screen: Google, Facebook, the New York Times. Apps that will never be on my home screen: yours.

Types of Civic Applications

The following is taken from ESRI's "Civic Engagement Apps Fall into Seven Categories" [though it could use improvement]:

  • Public Information: Maps are being used with greater frequency to communicate complex information that would not be quickly grasped in another format. These apps are effective at addressing transparency concerns, provide a channel for feedback, and communicate both where and why government money is being spent. Recovery.org, mapping the American Recovery and Reinvestment Act economic stimulus spending, is a good example of this type of app.

  • Public Reporting: The Federal Communications Commission (FCC) tapped into the power of crowdsourced information through the FCC Speed Test, an iPhone app that measures the quality and speed of a consumer's broadband connection. During the first six months it was available from the App Store, 1.2 million people downloaded the app and reported back information that helped the agency plan infrastructure expansion and determine policy. The captured data is visualized as a mapped surface that can be explored.

  • Solicited Comments: Apps don't have to be forever. When the Regional Transportation Commission of Washoe County, Nevada, wanted citizen comment on the Reno Sparks Bicycle and Pedestrian Master Plan, it worked with Esri partner CitySourced to develop an app that would let residents identify the locations for needed improvements, such as a crosswalk or a bike lane, simply by taking a photo of the location with a smartphone and writing comments in a form. These comments were captured and displayed on a web map. The app went up in summer 2010 and was taken down in early 2011.

  • Unsolicited Comments: Governments can learn about public opinion on issues and the effects of events through apps that gather constituents' posts on social media sites such as Twitter and Flickr. Social media maps on events such as the Gulf of Mexico oil spill aggregated and shared comments, photos, and videos that greatly enhanced the information available on conditions.

  • Citizen as Sensor: The Crime Tips app, from Esri partners The Omega Group and CitySourced, gives police many more eyes on the street. The iPhone/iPod/iPad app lets the user learn which crimes are happening nearby as well as anonymously report crime tips that will be forwarded to authorities.

  • Volunteerism: The Lifesaving App for the Android and iPhone, developed for the San Ramon Valley Fire Protection District by the nonprofit PulsePoint Foundation, crowdsources Good Samaritans. In instances of cardiac arrest, time is vital. The Lifesaving App lets smartphone users volunteer to be notified if someone nearby needs CPR. When a 911 call is received, the nearest CPR volunteer, who is in the best position to respond in timely fashion, receives information on the incident.

  • Citizen as Scientist: Individuals can contribute to collective knowledge with these apps. The free Mojave Desert Tortoise app lets users take a photo, find out more about this endangered species, and note location and other information about an individual tortoise.

More Repositories

1

adopt-a-hydrant

A web application that allows citizens to "adopt" civic infrastructure, such as fire hydrants that need to be shoveled out after it snows.
Ruby
661
star
2

skillshares

A collection of notes for internal Code for America skillshares.
Python
192
star
3

ohana-api

The open source API directory of community social services.
Ruby
183
star
4

codeforamerica.org-archive

The (former) @codeforamerica website
HTML
176
star
5

citygram

Subscribe to your city.
Ruby
170
star
6

howto

How To Do Things
169
star
7

glossary-bot

A Glossary bot for Slack
Python
116
star
8

brigade

The Code for America Brigade Website
HTML
100
star
9

naics-api

Basic API to return NAICS codes and information
Python
91
star
10

follow-all

Follow all the members of a Twitter list with a single click
Ruby
80
star
11

codeofconduct

Code for America's Code of Conduct
73
star
12

ohana-web-search

A mobile-friendly website for finding human and social services in your community
SCSS
68
star
13

textizen

An SMS survey platform built by CfA Team Philadelphia
Ruby
66
star
14

honolulu_answers

Easy answers to citizens questions
JavaScript
60
star
15

recordtrac

Manage and display public record requests, built by the Code for America 2013 Oakland team, maintained by @richaagarwal
CSS
59
star
16

open311dashboard

Visualizing and analyzing Open311 data on one unified, customizable dashboard
Python
58
star
17

beyondtransparency

Code for America's new book - Beyond Transparency ๐Ÿ“•
HTML
56
star
18

Transit-Map-in-TileMill

Map of transit (bus) system in Macon, Georgia using Tilemill
CartoCSS
54
star
19

intake

A Django project behind the Clear My Record website
Python
48
star
20

cityvoice

A place-based call-in system for gathering and sharing community feedback
Ruby
47
star
21

balance

A text message system for checking one's EBT card balance (SNAP benefits and more)
Ruby
46
star
22

pdfhook

A Python web application for converting PDF forms into PDF-filling APIs
Python
46
star
23

CutePets

Twitter bot that posts adoptable pets in your city.
Ruby
44
star
24

courtbot

Your friendly neighborhood court robot. Provides an api for getting court case information.
JavaScript
43
star
25

project-ideas

A place to collect ideas for CfA health projects
41
star
26

congress

Ruby wrapper for the Sunlight Congress API
Ruby
40
star
27

OpenTrails

OpenTrails (Open Trail System Specification) Converter & Validator
Python
39
star
28

wp-splost

This is the Wordpress theme for Macon's SPLOST website.
PHP
39
star
29

city-analytics-dashboard

โ›”๏ธ DEPRECATED Display google analytics from a city's website as a dashboard
JavaScript
38
star
30

opencounter

NOTE: This codebase was adopted by OpenCounter Enterprises Inc. and is now maintained in a separate repository. Please see www.opencounter.us for more information. Set up shop in your city.
JavaScript
37
star
31

citizen-onboard

How our government services work and don't work, inspired by @UserOnboard.
HTML
35
star
32

chime

A city-focused content management system
HTML
35
star
33

annual

Code for America's Annual Report
CSS
34
star
34

etl-for-america

A convening place for ETL, data integration, and "plumbing the pipes" of government data
34
star
35

three

An easy-to-use Python wrapper for the Open311 API.
Python
33
star
36

civic-issue-finder

UNMAINTAINED. An embeddable widget to find issues on the Code for America API
Python
33
star
37

promptly

Code for text message reminders
Ruby
32
star
38

trailsy

A trip planner and mapper for hiking/biking/riding trail systems.
CSS
31
star
39

open311

A Ruby wrapper for the Open311 API
Ruby
31
star
40

michigan-benefits

Digital Assister for Michigan
Ruby
30
star
41

apply

If you can read this, you should apply for a 2016 @codeforamerica fellowship! Ask current and former fellows questions at https://github.com/codeforamerica/apply/issues
28
star
42

cfa_coder_sounds

Sounds for Code for America Coders on GitHub Post Hooks (In House at CfA)
28
star
43

git-jekyll-preview

Preview your Github-hosted websites before making them live.
Python
28
star
44

wheresmyschoolbus

jquery mobile + rails app that shows you where your school bus is
HTML
27
star
45

autoclearance

Clear My Record: Automatically clear convictions under prop 64
Ruby
27
star
46

civic-tech-taxonomy

Standardized identifiers for categorizing civic technology projects
HTML
26
star
47

somerville-teacher-tool

Project has moved!
Ruby
25
star
48

public_art_finder

All the stuff needed to get a barebones Public Art Finder mobile website setup in your city.
JavaScript
25
star
49

prepared.ly

JavaScript
24
star
50

US-Census-Area-API

Simple geospatial API for US Census, see also https://github.com/codeforamerica/hack-requests/blob/master/census-area-API.md
Python
24
star
51

citybook

Create a resource directory from a contact spreadsheet.
JavaScript
23
star
52

blockee

A project dedicated to making our civic spaces sparkle again.
JavaScript
23
star
53

comport

Comport is a tool for law enforcement agencies to open their data and be accountable to their citizens.
Python
23
star
54

transpochoices

This project is no longer under active development
JavaScript
22
star
55

bizfriendly-web

An experiment in digital literacy lessons. The experiment is now over.
CSS
22
star
56

MuniciPal

๐Ÿ’ฌ Consulting city-dwellers about legislation near them.
Ruby
22
star
57

streetscope

A geocoder for OpenAddresses
JavaScript
21
star
58

geodata-checkout

Draw an area and view geodata inside that neighborhood as an interactive map, time-enabled KML, or GeoJSON
CSS
21
star
59

bizfriendly-api

An experiment in digital literacy lessons. The experiment is now over.
Python
21
star
60

srtracker

Open311 Service Request Status Site
Python
20
star
61

social-media-handbook

This is a guidebook for city government representatives on how to use social media to better engage their citizen communities.
HTML
20
star
62

honeycrisp-gem

A Rails gem with base styles and Javascript for Code for America products
Ruby
20
star
63

clean

Apply for CalFresh in SF
Ruby
19
star
64

world_bank_ruby

A Ruby wrapper for the World Bank Development Indicators API
Ruby
19
star
65

clientcomm-rails

ClientComm facilitates better communication between clients and case managers to increase the number of people who succeed on community supervision.
Ruby
19
star
66

311DailyBrief

JavaScript
18
star
67

vita-min

Get Your Refund & GetCTC code, originally named b/c it helps VITA in a minimal way
Ruby
18
star
68

primerpeso

CSS
18
star
69

NeighborDiff

NeighborDiff is a simple site for citizens to update and detail their neighborhood map through CartoDB.
JavaScript
18
star
70

openbus-api

JavaScript
17
star
71

bizport

HTML
17
star
72

pittsburgh-purchasing-suite

Python
17
star
73

chime-starter

A starter chime site for city governments for use with Chime CMS
CSS
17
star
74

muralapp

Mobile application which adds an interactive layer to the thousands of murals in the City of Philadelphia Mural Arts Program.
JavaScript
17
star
75

brigade-information

Data about Code for America brigades and other civic tech organizations for the CfA API
Python
17
star
76

census2pgsql

Scripts to import census data into a PostGIS database.
PLpgSQL
17
star
77

projectmonitor

ProjectMonitor is a CI display aggregator. It displays the status of multiple Continuous Integration builds on a single web page.
JavaScript
17
star
78

schoolselection

Rails app that displays public school information for parents
Ruby
17
star
79

address-normalizer

A simple tool that takes a CSV file with addresses and normalizes them.
Ruby
16
star
80

brigade-alpha

The old Code for America Brigade website. The new site at https://github.com/codeforamerica/brigade
PHP
16
star
81

pattern-library

[NO LONGER SUPPORTED] Code for America's previous website pattern library
PHP
16
star
82

clinical_trials_python

Python API for the ClinicalTrials.gov API
Python
16
star
83

gem_template

The Code for America RubyGem template
Ruby
15
star
84

engine-light

โ›”๏ธ DEPRECATED Simple app dashboard that let's you know if it is okay.
Ruby
15
star
85

CfA_Accelerator

JavaScript
15
star
86

connect

A robot that waits on hold so social service clients don't have to
Ruby
14
star
87

311fm

A 311 service request viewer built on the open311 api
JavaScript
14
star
88

shortstack

Inspired by Crunchbase, ShortStack is the CfA database for public software, products and government entities
JavaScript
14
star
89

address-iq

Reducing 911 calls and solving problems, one address at a time.
Python
14
star
90

streetsearch

๐Ÿ” Find multiple streets and addresses in text, get GeoJSON
Python
13
star
91

court.atlantaga.gov

Atlanta's official court website.
HTML
13
star
92

CutePetsDenver

This is a twitter bot that posts a random adoptable pet from Denver's shelter.
Ruby
13
star
93

vocatus

An automated advocate for patient rights
PHP
13
star
94

GridMapper

Map reports from first responders on a grid overlay. See https://github.com/mapmeld/GridMapAuth for password protection with Node.js
JavaScript
13
star
95

buildatlanta

Let's build a better Atlanta.
JavaScript
12
star
96

health

Meta repo to view all health project issues
12
star
97

open311_java

Java language binding (wrapper) to the Open311 REST API
Java
12
star
98

JobOps

Veterans Job Platform
JavaScript
12
star
99

food_trucks

A Mobile Food Vendor Management Application
Ruby
12
star
100

straymapper

A web tool to help reunite more stray animals with their human companions
JavaScript
12
star