Historical braindump

[bensheldon]

Glad to see you tackling this early. Hopefully you can be more alert to committing stubby repos than the last 2 years of fellows :-)

In my opinion, the main holdup to contributions was repositories lacking:

1. a clear description of what the project is and its purpose
2. screenshots or other clear examples of what the project actually does
3. Clear/comprehensive instructions for setting up a development environment

Also, you should follow up with @dthompson about the legal side, but we had a big issue with repos not having a LICENSE (and there wasn't a clear contributor agreement as one might expect for serious open source projects). Also, with nearly 200+ repos, the "Discovery" aspect of coming to Code for America's github account and seeing a ton of random-ass repos isn't particularly encouraging for external contributions either.

Speaking of random-ass projects, Github-Tidy was my contribution to reviewing the (poor) state of CfA's repos.

This was the analysis at the time:

We reviewed 245 of 259 total repos. This is what we discovered:

• ✩✩✩✩✩: 32 repos have no readme whatsoever
• ✭✩✩✩✩: 46 repos have an empty/generic readme
• ✭✭✩✩✩: 40 repos have only a basic project description
• ✭✭✭✩✩: 54 repos include basic install/config information
• ✭✭✭✭✩: 34 repos have a comprehensive readme
• ✭✭✭✭✭: 8 repos have a badass, awesome readme

In other words, 55% of our repos have little to no documentation (2 stars or below); when including the number of repositories with only basic install/config information, that means 78% of our repos have deficient documentation. That's bad.

[lovehandle]

Speaking of licenses, is there a specific license that you think would be preferable over others? To be totally honest, I really haven't spent that much time researching distinctions between various licenses (advantages, disadvantages, etc.). Would love to get some perspective.

Also, Github Tidy looks fantastic!

[bensheldon]

Code for America uses the MIT License. I also think there should be some sort of Copyright Assignment agreement for people outside of CfA making commits (you should have signed a Copyright Assignment agreement as part of your onboarding), but that's another @dthompson question.

Also, there is an existing template that is infrequently used (https://github.com/codeforamerica/cfa_template). It was created by the 2011 fellows and poorly communicated to the 2012 fellows, and you'll often find repos that have no other information about the project other than that copy-paste statement.

[mick]

We have standardized around the use of the 3 clause BSD LIcense (very similar to MIT) which can be found in the https://github.com/codeforamerica/cfa_template repo.

I love the idea of setting up templates for our work (tho we should be reusing and updating the the existing hard to find one)

[lovehandle]

Agreed. Didn't see the old one in the list of repos. Something about being buried under 275 repos like this.

[monfresh]

+1 for clear and comprehensive instructions both for setting up a dev environment and for setting up and deploying the project itself. I'm a big fan of documentation, and love writing detailed tutorials, such as this one: http://www.moncefbelyamani.com/how-to-install-xcode-homebrew-git-rvm-ruby-on-mac/ It's been viewed 84,300 times since I published it last April, and keeps getting hundreds of views each day, which shows you the need for clear instructions.

While trying to put up Adopt-a-Hydrant for DC, I came across some setup issues, and I documented some of them in the Readme of my fork (https://github.com/monfresh/adopt-a-hydrant), but I'm also planning on writing a more detailed blog post explaining how to get fire hydrant data for your city and how to extract the lat/long data from it, and where to plug it in the app.

[mick]

:+1:

[kmcurry]

+1 Mick's [image: :+1:]

On Tue, Jan 8, 2013 at 4:24 PM, Mick Thompson notifications@github.comwrote:

[image: :+1:]

— Reply to this email directly or view it on GitHubhttps://github.com/codeforamerica/readme/issues/4#issuecomment-12018016.

Kevin Curry Program Director CfA Brigade 757.613.8158 GMT-5 http://brigade.codeforamerica.org

[ryanatwork]

I made this last year to help install Ruby environments, not sure the usage stats on it - https://github.com/codeforamerica/cfa_laptop but I always still use it whenever I get a new laptop, although I used Rbenv now instead of RVM

Also maybe someone should consider taking http://codeforamerica.github.com and making it more like http://www.thoughtbot.com/community/ to make the repos a little bit easier to find.

Of course you can also just make a repo called documentation and document things that way.

[yesezra]

It seems to me that we're talking about two things:

1. How do we improve the discoverability and organization of our repos?
2. What standards should we suggest for documentation and maintainability of new repos?

I've never dealt with this many repos, and I don't have experience with shepherding open source projects, so I'm not sure I have the answers...but I'm happy to help brainstorm.

[bensheldon]

@ahhrrr :+1: :+1: :+1:

[Mr0grog]

I think the first thing to do is actually take some action around the analysis in Github-Tidy: delete those one and two star repos, mark them as deprecated somehow, or move them to another account (e.g. CfALabs or somesuch).

[mapmeld]

If we're going to have dozens of repos active in a year, I don't think github.com/codeforamerica - cleaned or not - is going to help us communicate or organize CfA's work. More cities will want the repos on their own Github (like https://github.com/honolulu). I agree with @ryanatwork's suggestion that we should make use of codeforamerica.github.com

I want to bring up http://codeforamerica.org/projects/ - a great list of completed projects, accessibile to non-technical people. I think it says "we know what we're doing" and "we can help" better than code. When we are showing a Github URL to the general public, maybe we should be sharing this URL instead. Some of our city contacts were overwhelmed by Github and stopped clicking on Github links (even Github Pages, yikes).

What if codeforamerica.github.com were a technical step up from the /projects page, with lists like 'projects in development' and 'developer / designer tools'?

[bensheldon]

Could you open a new issue for "How do we improve the discoverability and organization of our repos?" I want to keep this issue focused on repo tidiness (and will change the title accordiningly

Thanks.

On Thursday, January 10, 2013, Nick Doiron wrote:

If we're going to have dozens of repos active in a year, I don't think github.com/codeforamerica - cleaned or not - is going to help us communicate or organize CfA's work. More cities will want the repos on their own Github (like https://github.com/honolulu). I agree with @ryanatwork https://github.com/ryanatwork's suggestion that we should make use of codeforamerica.github.com

I want to bring up http://codeforamerica.org/projects/ - a great list of completed projects, accessibile to non-technical people. I think it says "we know what we're doing" and "we can help" better than code. When we are showing a Github URL to the general public, maybe we should be sharing this URL instead. Some of our city contacts were overwhelmed by Github and stopped clicking on Github links (even Github Pages, yikes).

What if codeforamerica.github.com were a technical step up from that page, with lists like 'projects in development' and 'developer / designer tools'?

— Reply to this email directly or view it on GitHubhttps://github.com/codeforamerica/readme/issues/4#issuecomment-12131073.

Ben Sheldon 2012 Fellow @ Code for America ben@codeforamerica.org 415.275.1776

[jpvelez]

We're struggling with this same issue of repo documentation in Chicago.

We just assembled a list of active projects to facilitate face-to-face collaboration at the hack night (new people don't know what's out there or being worked on) and to catalyze online collaboration on github, something we've had very little of. So the list a first step toward discoverability.

Now @GovInTrenches and I are tackling the documentation question. We're hunting for docs that meet @bensheldon's three criteria (project description, screenshot, dev environment), and we were thinking of using them as inspiration for a template. Maybe we could work together with CfA on this?

[Mr0grog]

We're hunting for docs that meet @bensheldon's three criteria (project description, screenshot, dev environment), and we were thinking of using them as inspiration for a template.

Is there anywhere public that you are collecting these? This sounds like an awesome idea; I'd love to see what you come up with and contribute to it whenever I run across something.

[bensheldon]

We're hunting for docs

A place to start might be Github Tidy

[jpvelez]

@Mr0grog These is now!

How's this for a plan of attack:

1. @GovInTrenches, @Mr0grog, myself, and anyone else who want to help assembles documentation worth discussing and put it in the doc.
2. We mull it over and pick the best bits.
3. We put together a badass template using these best bits.
4. We create a pull request for CfA's existing template - if appropriate. To be frank, I don't really get wtf is going on with all those files. (Otherwise, we make a new repo.)
5. We spread the good word.

Thoughts?

[GovInTrenches]

I meant to post this earlier, but one of the things that I've been bouncing around is the concept of grading the repos based on difficulty. We do this with cookbooks. (1 spoon for a beginner and 5 spoons for you better know what you're doing first)

One of the things that I'd like to avoid happening is a new brigade city taking up an app that's really complicated, getting frustrated with it, and giving up on it. If we made it clear that the repo needs somebody who is very experienced with Python - then the group would know ahead of time to recruit a Python person. Or - in the inverse - if we have a new civic hacker who wants to get their feet wet - the one star repos would be a good place to start.

[lovehandle]

@jpvelez I was confused by the CFA template initially, as well. As I understand it, the READMEs are organized by project type. (e.g. if you're creating a rubygem, use the ruby_gem.mkd file; if you're making a rails project, use the rails.mkd file). The idea is to generalize project READMEs to the type of project you are working on because the READMEs will differ greatly from one project type to the next.

[migurski]

@jpvelez how’s this going up in Chicago, four months on?