search

codeforamerica / brigade-alpha

The old Code for America Brigade website. The new site at https://github.com/codeforamerica/brigade
BSD 3-Clause "New" or "Revised" License
16 stars 18 forks source link

Brigade Projects Page Discussion #89

Open ondrae opened 9 years ago

ondrae commented 9 years ago

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.

screenshot A demo screenshot of a Brigade project list

The Audience

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

Inspirations

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:

Jaime-Alexis commented 9 years ago

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 commented 9 years ago

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 commented 9 years ago

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

volkanunsal commented 9 years ago

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 commented 9 years ago

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:

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

Card view of a project

cbracy commented 9 years ago

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 commented 9 years ago

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 commented 9 years ago

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 commented 9 years ago

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:

Based on these goals we came up with initial wireframes of Code for America Projects Hub, which you can see here: https://github.com/codeforkansascity/Code-for-America-Projects-Hub/issues/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.

code for america - projects hub by city filtered png

ondrae commented 9 years ago

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:

drewrwilson commented 9 years ago

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

image

tangospring commented 9 years ago

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:

code for america - projects hub html prototype

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 commented 9 years ago

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 commented 9 years ago

Can't just be the git repo url?

themightychris commented 9 years ago

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 commented 9 years ago

Notice I said git, not github :)

themightychris commented 9 years ago

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 commented 9 years ago

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 commented 9 years ago

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 commented 9 years ago

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 commented 9 years ago

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 commented 9 years ago

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

themightychris commented 9 years ago

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 commented 9 years ago

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 commented 9 years ago

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 https://github.com/codeforamerica/brigade-alpha/issues/89#issuecomment-76880048 .

tangospring commented 9 years ago

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 https://github.com/codeforamerica/brigade-alpha/issues/89#issuecomment-79180464 .

volkanunsal commented 9 years ago

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.

screen shot 2015-03-25 at 2 34 59 pm

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 commented 9 years ago

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 commented 9 years ago

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: https://github.com/codeforkansascity/Code-for-America-Projects-Hub/issues/25

ondrae commented 9 years ago

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 commented 9 years ago

@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 commented 9 years ago

@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).