Journalism as a city's API documentation

Journalism is literally the documentation of our communities, but the word documentation has special meaning in open source software. Open source projects usually come with documentation, guides, and references that serve as an operator's manual for the project.

If only every City Hall had an operator's manual.

Wouldn't it be great if looking up how an aspect of City Hall works could be like looking up example usage of the API of a well-documented open source project? Wouldn't it be amazing to have an API for our cities, an interface that would allow us to build projects with the city as the platform? Well, there is one. It's just hidden under layers of well-meaning bureaucracy.

I'm using the idea of an API in a figurative way, a metaphor for the civic engagement people have done in cities all along. There's also a literal API in many cities, an open data portal, as well as blogs, real-time data feeds, social media, and projects like LocalWiki, a wiki for geographical locations with a great API.

We can document the figurative APIs of the city: the processes, meetings, permits, and policies that govern the daily operations of local governance and the ways citizens can make an impact.

We can also document and use the literal APIs that provide raw information about our cities: the data portals, real-time feeds, and local wikis and blogs.

We need various types of documentation:

  • Explanation. Complex topics need to be explained in simple ways.
  • Tutorials. To be engaged citizens we need to understand how to engage.
  • Reference. We need an organized searchable guide to our community's knowledge.
  • Notifications. We need to stay updated on what's happened recently.

Too many publications covering local government are only notifications, streams of content that only make sense to those who have already spent large amounts of time familiarizing themselves with the inner-workings of their city, county, or state.

Increasing the civic literacy of a community requires:

  1. onboarding with the basics of how to get involved
  2. actions they can take to make a real impact
  3. resources they can use to gain a deeper understanding
  4. updates on what's happening to stay informed

As we've learned from open source software: projects with strong documentation have active communities.

Let's apply that lesson to the way we report on & participate in local government.

Seth Vincent

Seth makes weird arcades, writes JavaScript, and builds civic technology.
sethvincent.com
twitter.com/sethdvincent
github.com/sethvincent