Brigade Projects Page Discussion

[ondrae]

Description

It is time to build a site that shows off the projects of the Civic Technology movement. Let us discuss what we must do to make this site as useful and successful as can be.

A demo screenshot of a Brigade project list

The Audience

• Neighbors looking for finished projects that are already set up for their use in their neighborhoods.
• Brigades looking for finished projects to redeploy in their cities.
• Brigades looking for projects that still need work to point new volunteers towards
• People looking for all available apps within certain category - transportation, health, etc
• Press

Features

The site should show off all of the Brigade projects in a filterable way, while encouraging discussion and contribution.

Inspirations

• https://www.gov.uk/transformation
• https://18f.gsa.gov/dashboard/
• http://opengovhacknight.org/projects.html
• http://codeforsanfrancisco.org/projects/
• http://v3-brigade.herokuapp.com/projects
• https://www.govcode.org/repos

Discussion Tasks

• Have a discussion about what is needed on a good projects list
• Do some other user testing
• Decide on the best technology to build it in

Technical Tasks

• Add the status column to the CfAPI as in CfAPI #133
• Add the tags column to the CfAPI as in CfAPI #193
• Build better search functions in the CfAPI as in CfAPI #194
• Build the /projects page!

History

Code for America has attempted this before, creating sites where there was an unsustainable amount of effort needed to keep the data up to date. We've solved that problem now that we have an always current civic technology project list from the CfAPI

As this page will most likely live on the Brigade website, I'm starting this conversation here. The history of the Brigade site is:

• v1 - online - Code - A Rails site with many contributors. It served the Brigade well as it was growing. As Code for America became better at supporting the volunteer groups, we needed something different.
• The CfAPI was built as reaction to how Brigades were operating themselves. We now meet them where they are, instead of trying to get them to log into our site.
• v2 (production) - online - code - Powered by the CfAPI and works great, yet is built quickly with PHP and Javascript. It is kind of a cobweb of dependent parts, and will be hard to have lots of outside developer help on it.
• v3 (under development) - online - code - A Python Flask app built for quick and easy improvements.

[Jaime-Alexis]

Quick question: any reason if we're logging these as part of "civic technology movement" that it wouldn't be on CfA main site vs. just on Brigade site? Also, is it just civic technology movement or gov technology movement?

[ondrae]

Good question. If what we build proves to be useful for the Brigades, then we can easily include it on our main website as well. Right now, I'm planning to just filter on Brigade projects, not including the Fellows or Governments fine works.

Removing one line of code will include all projects.

[BretFisher]

• My goal when reaching out to @ondrae was to have a site that allowed the best looking, best usable, most popular etc. apps show up in a visual way. Something that's easy to use by non-tech for seeing what we do, yet something that brigades would be interested in seeing what's been released. Tags and search would be key, but the community would rate/:thumbsup:/comment on them.
• start out simple, showing screenshots of solutions brigades (and fellowship?) have built. The stuff on cfa.org is just fellowship-built as I understand it.
• cream should rise to the top (HN style. Maybe with comments?)
• I feel like a site highlighting the best in civic apps is what we're asked for by people coming to hacknight, by local leaders, etc., but that a site just listing all CfAPI repos would be hard to find the cream/best. We'd have to work hard to keep it from being a sea of microservices and old repos. May be opposing goals.
• Long term dream: it turns into cfa-npm and you can deploy civic apps with one line ;)

I'll pass this issue around. Looking forward to what we come up with.

[volkanunsal]

We at BetaNYC have been undertaking a similar project. It's a much less sophisticated project, a clientside Javascript app that depends on the Github API for much of its functionality. My design goals are to make Github the only backend to update the projects list –– all data will be fetched via API calls –– and it should be easily deployable to Github pages.

The only problem I have run into so far has been the limitations on how many projects you can search through Github API –– that number it turns out is precisely 14. But if we replace CfAPI with Github for the search functionality, it should work out just fine, as long as the data is complete. I am hoping that CfAPI has a write endpoint, as well.

Aside from everything that "brigade" supports, we are also planning to support a way for project owners to award badges to worthy participants through the civic.json protocol. There is a bit more planning that will need to go into how that works, but this feature will be tapping into a microservice powered by Mozilla's OpenBadges platform, which is a work in progress but seem to be mostly functional.

[zmon]

We have just started to talk about this in KC as a tool to help hack night attendees connect with local projects. Our idea is to use CfAPI along with a Google spread sheet to for information that CfAPI and GitHub do not easily provide. civic.json looks good.

On night a group started to look at the CfAPI data for project ideas. But the data does not indicate if it is a "good" project or not. So BretFisher comment would be a great solution for this use. It would be great if we had reviews of some sort or links to media coverage for each project, or some sort of badge system that volkanunsal talked about in his comment. It would be great if people that forked and tried to deployed it could comment on their experience.

The fields we are thinking for the spread sheet are:

• Category: Health, Transportation....
• Technologies: a detailed list that the project uses, so instead of JavaScript we would get
  HTML, JavaScript, jQuery, Bootstrap, Google Map API
• Who the lead person on the project is.
• Project progress: Idea, Definition, Development/Coding, Deployed, Dead
• Link to project graphic, some sort of mockup/screen shot/eye candy
• Civic Need that is meet by the project or a better description.

We need this to communicate what we might tell someone at the CFA Summit about a great project we know of and why they should deploy it.

A initial mockup that was done by Oleh Kovalchuke

[cbracy]

I'm kind of with Jaime-Alexis on this one just because this is of huge importance to the Code for All community so leaving out those projects would be unfortunate. Maybe we can have another tag/sort that is by program? ie: Fellowship tools, Brigade tools, Code for All, other, etc?

[cbracy]

However, I would say that this should be a catalog of tools that are redeployable. I don't think it should include proprietary tools or vendors.

[themightychris]

One of the best things CfA could do here I think is publish and maintain JSON files containing moderated lists of "official" tags and categories on a server that supports CORS. The CfApi spec should still allow for arbitrary strings in the categories and tags fields, but these hosted data sources would be easy for people to plug directly into their local project database tools and gently steer data towards a unified taxonomy.

I could picture the suggest-as-you-type input for tags/categories on Laddr's project pages showing a little CfA flag next to these

[tangospring]

This is a much needed discussion.

We have started to work on Code for America Projects Hub here in Kansas City couple weeks ago (great minds think alike ;-).

The initial project goals were:

• foster multi-brigade collaboration (connect skills and needs across the nation),
• increase supply of civic ideas (to broaden the idea funnel),
• ease onboarding for new members,
• reduce project redundancy,
• provide CfA projects overview with ability to filter and sort projects.

Based on these goals we came up with initial wireframes of Code for America Projects Hub, which you can see here: zmon/Code-for-America-Projects-Hub#1

HTML/CSS (Bootstrap) prototype of the main hub page is almost completed (should be done by Monday).

The Audience and the Needs

1. Primary: Brigade Members wishing to apply specific skills to specific civic projects.
2. Primary: Civic minded people, who might have great ideas, but do not have skills or background to hack them.
3. Secondary: People wishing to use the completed apps.
4. Secondary: New brigade members wishing to know what is going on.
5. Secondary: Civic organizations wishing to add and use apps.

Since initial meeting the scope has expanded to include 'People' page (in line with @volkanunsal suggestion). The primary goal of 'People' page is keep brigade members engaged. The secondary goal is to help project leaders find people with skills to work on the project. Design provides card summary view of brigade member skills and contributions similar to the projects card summary.

@ondrae, adding discussion capability to projects pages is a great idea. Initially the thought was to rate projects by starred and watched; discussion badge adds to project validity. I have added discussion badge to the wireframe.

@cbracy, CfA project badges (Fellowship tools, Brigade tools, Code for All, other, etc) – these should be included in the projects cards and to project filters (see updated mockup).

@volkanunsal, people badges (project leader, idea, hacker-extraordinaire, etc.) – these should be included in the People cards and project cards.

[ondrae]

Great ideas everyone.

@BretFisher "deploy civic apps with one line ;)" Check out our work at https://cityvoice-heroku-builder-dev.herokuapp.com/ and https://dashboard-setup.codeforamerica.org/ to see how we've been trying it so far.

@cbracy @Jaime-Alexis If this goes well, we'll put it on the front page.

@themightychris I'm open to any terms or schema we want to use, as long as its not obtuse.

@volkanunsal @tangospring Good ideas! Great wireframes. We have free myBalsamiq available if anyone else wants access.

I'm going to argue that we should keep people out of it for now though. Delay on both the people cards and the badges. Those are both great ideas and useful services, yet they should be their own project. I'm working on something to pull in lots of info about people, from github, attendance at hack night, etc. We can build badges and people profiles off of that project.

For now, we should stick to just displaying and celebrating projects, though we can show off who worked on them. This could include ranking the projects, maybe even comments, but for now I'd rather point discussions about them to wherever that project wants to have its discussions.

I definitely want to put off the idea of connecting people to projects based on skills. Its so desirable yet, just getting the projects appearing in a useful way is a project enough.

I do have some inspiration links for how we could connect people to projects that need help though:

• http://www.codeforamerica.org/geeks/civicissues
• https://18f.gsa.gov/dashboard/project/midas/
• https://assembly.com/

[drewrwilson]

Code for Germany has a great one too: http://codefor.de/projekte

[tangospring]

Thanks for your kind words and the inspiration links, Andrew.

I can see from the inspiration samples that you are exited about developing marketing website, where the primary audience is media and curious public. Marketing websites benefit from the exemplary case studies.

Our inspiration came from the trials and tribulations of new brigade members in the relatively small brigade in Kansas City. We need tools and help from other brigades, and we would like to help to develop interesting projects in other cities (or simply branch them to apply locally). We need to know where the help is needed and do we have appropriate skills to help.

The purpose of Projects Hub is more utilitarian: to quickly identify relevant projects out of hundreds. Therefore the primary concern in designing the hub was information density and filtering/sorting.

Additional concern, addressed in the design, is to help public to make an informed contribution of new civic ideas to code (occasionally civic-minded people do not know how to develop the idea).

Screenshot of HTML/CSS prototype as of today:

I think your arguments apply to the marketing website, less so to the projects hub.

Comments/discussion threads preserve history of decision making. It is a good idea for projects web app, and should be encouraged. I do not have a good data on civic project trolling. I guess we could provide an option for disabling comments, if needed.

The 'People' screen and the gamification badges. Agreed it is an enhancement to the hub. The primary goal here is increasing engagement of brigadiers, and promoting cross-brigade collaboration. This is the case, where gamification is useful. The 'People' part of the project is especially important for nurturing small brigades, where we might have deep skills in narrow areas.

[themightychris]

I don't think this is necessary for the initial version of a new project browser, but something that might be worth considering in parallel is some sort of optional global ID scheme that allows projects to reference each other. I'd propose something similar to mobile app IDs in reverse DNS format like org.codeforphilly.CyclePhilly. Feed implementations could just generate this from some existing identifier like org.codeforphilly.[repoName] or have a field people can set directly. If a project has one you could document that another project published by another brigade is a fork/deploy of it.

[BretFisher]

Can't just be the git repo url?

[themightychris]

I think one of the great things about the CfApi and possibly a key reason for its wide adoption is that it doesn't mandate any centralized database, specific vendor, or specific workflow. As altruistic and useful as GitHub feels, they're still a proprietary vendor and a fashion. This network should outlive most of the hip development solutions of today. Imagine if we set this network up a decade ago and now were dealing with project identifiers anchored in sourceforge URLs?

Also something we've tried to avoid in Code for Philly at least is ingraining in our DNA that one project = one source control repo on github. What if a project doesn't need source code? What if it's just a deploy of another brigade's well-maintained repo and you don't want/need to fork? What if the project consists of many repositories? What if it starts under a volunteer's personal GitHub account and then gets moved to the brigade or a partner's organization?

The great thing about reverse-DNS identifiers is that they can simultaneously be globally unique and descriptive without needing a centralized way to issue and track them -- just make sure all the ones you or your organization create are prefixed with a domain you own. This fits really well with the existing CfApi design and philosophy.

For any brigades that do follow 1 project = 1 git repo under our official organization dogmatically, generating the unique identifier field could be done with a simple spreadsheet formula to change github.com/CodeForMyPlace/MyProject to org.CodeForMyPlace.MyProject. A deploy of an existing app can just be the domain its setup at and you don't need to clutter your organizations github profile with a fork you're going to forget about and never update.

These identifiers will also come in handy once this central project site, or any other tools built to consume CfApi feeds, start getting more complex. Once you want to start storing/displaying any metadata collected outside the projects.csv feed, you need a way to link it to the rows in that spreadsheet that will survive it possibly being reordered or having some values changed. Once you're doing more than displaying whats current in the feed, you really need a stable way to reference individual projects.

The field would have to be initially optional to support a gradual phase-in, but I'm not sure how any system built on top of CfApi could reliably do anything involving referential data without them (think commenting, voting, linking). Maybe more complex CfApi tools that need the identifiers could just ignore projects without them so it could be an opt-in ecosystem like the initial CfApi launch was

[BretFisher]

Notice I said git, not github :)

[themightychris]

Ah, my bad. Still though, s/sourceforge/svn/. A repo URL is still more of an implementation detail that should be subject to change through the life of a project and its network of deploys, and shouldn't be a requirement.

[migurski]

Imagine if we set this network up a decade ago and now were dealing with project identifiers anchored in sourceforge URLs?

If they were still valid URLs that represented the project source code’s chosen location, why would this be a problem?

But, my inclination is that if we go for a global ID scheme we not use natural keys for projects, and instead mint unique numeric IDs. Projects will change organizations, new people will take them over, source will move from Github to someplace else, and we’re going to want something permanent but completely un-precious to refer to them. Opaque numbers win at this.

[themightychris]

The problem with minting unique numeric IDs is you then need a central authority issuing them, which completely breaks the CfApi's current decentralized nature. A project in code for philly's feed then couldn't be referenced by others until we went to CfA, got an ID number for the project, and then added that ID number to the project in our database. There's a good reason Apple and Google both use reverse DNS identifiers for apps.

[migurski]

You’d need that no matter what to guarantee no collisions, and central authority is sort-of what the CfAPI is doing. We could also use one of these sources of integers in the cloud: http://missionintegers.com, http://www.brooklynintegers.com

[themightychris]

Reverse DNS identifiers don't guarantee no collisions any less than cloud integer services if you're relying on feed publishers to populate their own feed. Both offer the same level of guarantee that identifiers are unique but one has a global hosted service dependency. CfAPI is presently implemented as an aggregator of decentralized feeds (what it should be), cfa commons withered because it tried to be a central authority.

[migurski]

Sorry, wasn’t clear: my thinking is that we don’t want to rely on feed publishers to populate their own unique IDs.

[themightychris]

If the feed publishers aren't populating unique IDs though, and your storing or associating related data with rows from those feeds, how do you deal with changes in the feed? If I change a project's title and/or URL, how do you know to update the existing project rather than create a new one?

I can't see any way for advance tools that need to store associated data working with self-published feeds unless publishers implement unique IDs. It could be gradually introduced by making the unique ID column a requirement for inclusion in the more advanced tools.

[ondrae]

Wow @tangospring you all are having some great progress at http://codeforkc.org/Code-for-America-Projects-Hub/prototype/CfAprojectsHub.htm

We're steadily working on the Technical Tasks listed in the main post.

[tangospring]

Hello Bret,

Sorry, I have missed your question, when you asked it.

Here is the GitHub repo for this project:
https://github.com/codeforkansascity/Code-for-America-Projects-Hub .
Relevant links are in the readme.

The IA, workflow, interaction design, HTML/CSS scaffolding are mostly
complete (should be more complete by Monday). Google forms are functional
already, need to be hooked up to front end.

Thanks,
Oleh

Oleh Kovalchuke
(816) 808-6177

On Mon, Mar 2, 2015 at 9:21 PM, Bret Fisher notifications@github.com
wrote:

Can't just be the git repo url?

On Mon, Mar 2, 2015 at 4:30 PM -0800, "Chris Alfano" <
notifications@github.com> wrote:

I don't think this is necessary for the initial version of a new project
browser, but something that might be worth considering in parallel is some
sort of optional global ID scheme that allows projects to reference each
other. I'd propose something similar to mobile app IDs in reverse DNS
format like org.codeforphilly.CyclePhilly. Feed implementations could just
generate this from some existing identifier like
org.codeforphilly.[repoName] or have a field people can set directly. If a
project has one you could document that another project published by
another brigade is a fork/deploy of it.

—
Reply to this email directly or view it on GitHub.

—
Reply to this email directly or view it on GitHub
#89 (comment)
.

[tangospring]

Thanks Andrew, we have good people here in KC.

Oleh

Oleh Kovalchuke
(816) 808-6177

On Fri, Mar 13, 2015 at 12:46 PM, Andrew Hyder notifications@github.com
wrote:

Wow @tangospring https://github.com/tangospring you all are having some
great progress at
http://codeforkc.org/Code-for-America-Projects-Hub/prototype/CfAprojectsHub.htm

We're steadily working on the Technical Tasks listed in the main post.

—
Reply to this email directly or view it on GitHub
#89 (comment)
.

[volkanunsal]

I wanted to share the current state of the BetaNYC projects list, which I am working on. We have gotten it to run entirely on the clientside, driven by the CfAPI, Github API and Discourse API.

There is still a bit of work to do for us, including a link between our CKAN deployment and the individual projects. We are also still working on our taxonomy in order to get it in line with NYC's own taxonomy.

Let me know how it looks, works ( or doesn't!).

[ondrae]

Wow, good work Volkan, and its live already.

We've almost got support for status in the CfAPI. It can pull either a spreadsheet or a "civic.json" file like you use at BetaNYC.

I really like how you tied it in to your forum as well.

[tangospring]

It looks attractive, Volkan. There are a few obvious interaction issues on the very first page: search is button, not an input; icons in the tiles are not descriptive enough (I recommend adding text -- it's fairly well established design approach). There could be more issues deeper in the site. Talk to someone with usability or IxD background in the brigade.

We, in the other City ;-), are not sitting idle either: http://codeforkc.org/Code-for-America-Projects-Hub/

The site has issues as well: zmon/Code-for-America-Projects-Hub#25

[ondrae]

Hi everyone. We added some new features to the CfAPI that should be useful for the projects pages

@volkanunsal added search! The docs are at http://codeforamerica.org/api/#api-projects

Some examples are:
http://codeforamerica.org/api/projects?q=Bicycle
http://codeforamerica.org/api/organizations/Code-for-San-Francisco/projects?q=Bicycle

We also added support for a project "status" attribute. It'll take some for groups to start using it but support is there. still need to write some docs for how to include it. You either add it to your projects list spreadsheet or if you use a GitHub org account as your list, you can add a civic.json file to each project. BetaNyC has examples https://github.com/MTA-Service-Alerts-beta-nyc/service-alerts/blob/master/civic.json. Clearer docs for status coming soon, but wanted to let you all know.

[themightychris]

@ondrae awesome work!

I noticed an id property along with projects in the responses, are these being assigned by the feed consumer on codeforamerica.org? If so, what field(s) in our feeds do we need to avoid changing to prevent a new id from being generated for a project that already has one?

[tmaybe]

@themightychris that id property shouldn't be relied upon to remain consistent, as it's generated by the API's database which, at the moment, is designed so that it can be rebuilt from its sources at any time (in which case completely new IDs would be assigned).