Nerd Alert Issue 18: It’s GitHub’s Birthday!

Github turns 7 years old today!


HOT LINKS

What we're reading this week

  Adam: I don’t agree with everything Eugene Wei has to say about why tech companies are largely beating publishers at their own game but he makes so many good points that I think this take on the recent rumblings about Facebook hosting content directly for publishers is worth reading carefully and digesting.

  Ben: Lego launched a new video game this week, and forgot to buy its domain name. A journalist bought the domain, and now it’s an ethical discussion. What do you think of the journalist’s actions, and the community reactions?

  Denise: Cindy Royal, a Texas State University professor and recent Knight Journalism Fellow at Stanford University, makes a case for coding to be taught across disciplines at colleges. Coding education, she says, will help support the future of journalism (and so many other fields).

  Kaeti: As a distributed team, we do a lot of virtual client meetings. Erika Hall’s article on presenting design remotely is so relevant to my interests. Her core advice can apply to any presentation or meeting: get to know your stakeholders, stay in constant communication, and maintain clear expectations.

  Meredith: My background in literacy attracts me to the idea of programming languages and toolkits for the mind. Language, vocabulary and grammar impact your perspective and your strategies to solve problems.

 Nick: Genius.com, the people behind my favorite hip-hop lyrics site rap.genius.com, are now taking their mastery of annotations and applying it to all kinds of web content. John Resig (the creator of jQuery) annotates the original jQuery code from 2006, and here are notes on Obama’s State of the Union Address. It’s still in beta, but I hope to see this or a spin-off as an open platform for commentary on the web. Annotate all the things!

  Ryan: The INN Nerds have been looking at ways to simplify and streamline documentation of our visual styles in a way that will allow us to get new projects off the ground more quickly in the future. See this post about living style guide tools for a thorough list of tools meant to help lessen the effort required to document your favorite flavor of CSS and keep said documentation up-to-date.

  Will: PDFs are great, except when you scrape data out of them. Jeremy Merrill shares his solution to this problem, using the command-line version of Tabula to build reusable scrapers for automatically generated PDFs. Use them as a model, and liberate your data from PDFs too.

  Bert: One of my cousins is going to space on Monday!


We Made a Thing

Our projects, manifest

A screenshot of the new Current.org homepage, featuring the navigation and two celebrity photos in the featured image spot.

Current.org launched their redesigned site this week! We're happy to see another site using our work.


Shout Out

Work we admire by our journalism peers

To all our friends who participated in #SNDMakes, you’re awesome! We look forward to seeing what you come up with for improving picture stories today.


Some Other Stuff

Gather ye rosebuds

LISTEN: The tick, tick, tick of doom.

COOK: What if you don’t like thick, spongy pancakes? Try this Norwegian recipe.

WATCH: This month's News Nerd Book Club book was Indi Young's Practical Empathy. We were pleasantly surprised when she visited the book club hangout to talk with us. Here's a video of her talk about practical empathy at UX Lausanne 2014.

GIF: From member site Wisconsin Watch’s fracking sand gif collection comes this masterpiece:

A line art animation of a bull, with horns made of sand. The bull's horns flex up and down, rearranging the sand. When the horns are pointed up, the bull snorts, and grains of sand fly out of its nostrils.

Nerd Alert Issue 17: Gooseneck Barnacle Cathedral

Barnacle geese were once thought to develop from goose barnacles.


HOT LINKS

What we're reading this week

  Adam: Communicating securely with colleagues and sources has received a lot of attention in the past couple of years but it’s often still a bit intimidating for non-technical folks to know where to start. This week WNYC’s John Keefe wrote a step by step introduction to setting up email encryption that a provides a gentle introduction to this sort of thing.

  Ben: Most of our readers have probably collided with Git at some point in the past, or had to explain it to someone. The Git Parable, by one of the cofounders of GitHub, is a pretty awesome intro to the version control software that rules our lives today.

  Denise: Time for some inspiration: The annual IRE Award winners were announced this morning. Congrats to the winners (including some INN members)!

  Kaeti: I really enjoyed this Made By interview with Chris Coyier (of CSS-Tricks, CodePen and the Shop Talk podcast). A good reminder that expertise is born of lots and lots of practice, not magic. Plus I’m always happy to see more tech people choosing to work in the midwest.

  Meredith: I prefer Twitter to other social platforms. I am fascinated by the ways that different people use it professionally and personally. Sarah Marshall offers 15 tips for using Twitter for News gathering.

 Nick: In Nerd Alert #14, Kaeti shared an article by Sailor Mercury on “Code Like A Girl”. I almost re-shared it here because I thought it was so awesome but Kaeti saved me from the dreaded re-post. Instead, you should take a look at Sailor Mercury’s kickstarter to make a series of zines on computer science called Bubble Sort. I used to collect the zine 2600, but this is going to be so much better.

  Ryan: If you're new to the command line, it can be daunting, but stick with it. Learn to love it. Powerful tools always have a steep learning curve, but the payoff is usually worth your trouble. Olivier Lacan's post covers the Unix $PATH environment variable, which plays a central role in determining the behavior of the command line. It's a great primer for those that are new to the command line and want to understand the basics, but also has some helpful tips for well-seasoned users.

  Will: With the Apple Watch due in stores later in April, read how Apple secretly built the thing, without any real idea of what they intended to create.

  Bert: Which comes first, the README or the project?


WE MADE A THING

Our projects, manifest

We now offer data consulting, helping you clean data, find stories, and build custom news apps. Last November we launched Power Players, and we look forward to creating something new!


SHOUT OUT

Work we admire by our journalism peers

SRCCON's list of session proposals is automatically updated by a chatbot. Here's the code behind BMO's ability to clean and sort the data, and Erin Kissane explains how it works in this Source post.


SOME OTHER STUFF

Gather ye rosebuds

LISTEN: Uptown Funk is topping the charts. Here Voldemort’s hot take.

COOK: Prepare and eat some Spanish gooseneck shrimp.

WATCH: Romance is in the air!

GIF: The Internet - how does it work?

A gif showing the interconnection between a home computer, an ISP, a central router, a government computer, a satellite ground station, and an undersea cable. The illustration is done in David Macaulay's distinctive style, as seen in books such as Castle, Undergound, and City.

Announcing Largo Version 0.4

largo-sqWe're excited to announce a new version of Largo, the open source WordPress framework we build and maintain for our member organizations.

Version 0.4 is a huge update that's been in the works for a while. In this release, we've more or less rebuilt the Largo theme from the ground up to make it more stable and easier to use. Here's a list of some of the things included in this update:

wcijProbably the most visible change is the addition of a number of new homepage layouts, which are much more visual and "magazine-like" to really highlight the feature reporting that many of our members are doing. We've also retained and polished up the previous homepage layouts (with the exception of the "carousel" layout, which is deprecated in version 0.4) and have added a new homepage framework to make it much easier to create your own custom homepage layouts from a child theme. Many of the new layouts also allow a user to switch between viewing "top stories" and "all recent stories" in a traditional "river" view, remembering their preference on subsequent visits.

Faith-based state group seeks Waupun prison abuse probe   WisconsinWatch.orgWe've also completely redesigned the article template to allow for more easy creation of immersive stories. The new default article template in Largo removes the sidebar to reduce distraction and adds a new featured media area at the top of the story with support for a large "hero" image, video or other embedded content (maps, audio, etc.). If you prefer the traditional two-column layout on story pages, we've kept that, too. You can simply select the template you'd like to use in the theme options and will have the option to override it on select stories. These improvements also include streamlining the publishing interface to make it easy to add and manage featured media by reducing the number of boxes you have to search through to find what you're looking for.

read-nextThe bottom of the article page template is now a WordPress widget area to make it easier to rearrange the elements that appear there. This includes the addition of a number of new widgets for related content, author bios, and an optional disclaimer that you can easily add to the bottom of all your stories, or selectively override on a per-story basis.

Site navigation is also cleaner, easier to manage and more mobile friendly, including an option to use a "sticky" header that remains visible when a user scrolls. Article pages now also have a sticky footer with social sharing links, the ability to easily follow authors and topics, and more.

follow

And we've replaced the clunky older/newer posts navigation used on many pages of the site with a simpler "load more posts" infinite scroll.

catCategory pages have been redesigned to give more prominence to featured stories and it is now possible to create and use custom sidebars on category and tag pages. In addition, we've added a new optional "content type" taxonomy to allow you to group stories by type. For example, if you'd like to have a page for just your data projects without having to use categories or tags, now you can!

User profiles are also now easier to manage with the option to upload avatar photos directly in WordPress instead of relying on Gravatar and with better validation for social media accounts to make sure your accounts get linked up correctly. We've also added a new widget to display a list of the writers and editors on your site with their avatar photos, titles, bios, etc.

optionsOn the admin side, we've tried to simplify wherever possible and have moved less-frequently used settings to an optional tab of the theme options to keep them easily available but out of the way. This includes things like optional taxonomies and a number of new integrations with services such as Google Custom Search that you can use to enhance the functionality of your site. One additional option allows you to easily change the color scheme of your site using a LESS/CSS customizer directly from the admin without having to edit your theme files directly.

For developers, we've reorganized the theme files in a way that we hope will make it a lot easier to develop child themes based on Largo. You'll also notice that we've begun to add unit tests for the theme, helper functions for debugging, and more hooks, filters and constants to make it easier to add, remove or modify various pieces of Largo functionality. We also have an updated sample child theme that includes ample documentation and recommended best practices for working with Largo. We welcome your feedback if there's anything else we can do to make your lives easier.

helpdeskAnd last but not least, we've completely revamped the Largo documentation, added a knowledge base with answers to our most frequently asked questions and implemented a new help desk system to better keep tabs on your questions for us.

Oh right, and the ubiquitous "assorted bug fixes."

Updating to the new version is as simple as downloading the new theme (zip) and replacing your existing copy of the Largo parent theme. Then, when you login to your site for the first time, you'll be prompted to apply a database update to make sure all of your settings are preserved. As this is a major update, we strongly recommend creating a backup of your site before making the update and, ideally, testing the new version on a staging site to make sure you have a handle on the changes before applying it to your live site. Just a reminder that if you require more assistance making this update, we offer paid services and we'd be happy to help. Details on that program can be found here.

For INN members who host their sites with us, this update is available today but we'd like to spend some time working with you to walk through the new features. Please drop us a line at support@largoproject.org if you'd like to be among the first sites to make the update, otherwise we'll be reaching out to you in the coming weeks to schedule these consultations.

Thanks to every member of the INN Nerds team who worked on this release, particularly Ryan Nagle, who took lead on this one, but also to Meredith Melragon who did a lot of the work improving our documentation, Kaeti Hinck who jumped in late in the cycle to help us polish the visual design, and our software apprentices Ben Keith and Will Haynes who both contributed a lot of code to this release. Thanks also to a couple of open source contributors, particularly Ben Byrne and Daniel Bachhuber.

The next release! 0.5 will be focused on improving performance, developer documentation and evaluating third-party libraries, as well as some continued improvements to the design of the default theme. It is scheduled for release at the end of March. We're now keeping the Largo roadmap public on GitHub, so you can see more of what's planned for future releases.

20+ Free And Discounted Tech Tools And Services For Nonprofits

INN has recently compiled a list of tech tools and services that offer special deals to nonprofit organizations. Here are a few of the tools and services from the list that our team uses:

Balsamiq is a tool for creating mockups and wireframes for websites that has some really nice collaborative features to allow you to share your designs and get feedback from your team. They offer free desktop licenses for their software to nonprofit organizations and open source projects or you can get a free year of their cloud-based wireframing tool. Learn more.

Buffer is a tool for scheduling social media posts that is very handy if you want to load up a bunch of posts all at once but have them trickle out over the course of the day. They have a free basic plan but offer nonprofit organizations 50% off of their paid plans which have a number of more advanced features. Learn more.

GitHub is a popular place to share and collaborate on code that is widely used in the open source and journalism community. The service is free to use unless you need to keep repositories private but they also provide free bronze plans (up to 10 private repositories, normally $25/month) for use by non‑profit organizations and charities. To take advantage of this program you must provide proof of 501(c)(3) status. Learn more.

Google offers nonprofits free Google Apps for Business accounts (email, calendar and cloud storage) through their nonprofit program. They also offer a free monthly allowance of search ads (called AdWords) through their Google Grants program and special functionality tailored to nonprofits on YouTube. Learn more.

Hipchat is a simple, but very powerful group chat application that allows you to create private or public chatrooms and also video chat, audio chat and screen share with your team members. It also has a bunch of add-ons that allow you to connect other services to your chat and receive notifications (we like to use it to keep tabs on our github repos. They offer free licenses to charitable organizations. Learn more.

MailChimp is a popular email list management tool that INN and many of our members use for email newsletters. They have a pretty generous free tier (12,000 emails to 2,000 subscribers monthly) but once you outgrow that they also offer nonprofits a 15% discount. Learn more.

Those are a few of our favorites, but be sure to check out the complete list and if you know of any others we should add, get in touch and let us know or drop a comment below with the details.

Using Fabric for WP Engine WordPress Deployments

One of my first tasks at INN was to familiarize myself with the tools and technology the team currently uses.

What I noticed was that our deployment process was pretty darned manual. We host a number of our WordPress sites on WP Engine and while they allow deployment via git and access via SFTP, they don’t give us shell access to the server. So our deployment process up until this point has involved an FTP client, dragging and dropping files for transfer, maybe picking and choosing parts of our code to deploy based on what we've been hacking on. This approach works, but is fragile and requires a lot more thinking than I'm typically willing to do. Remember, laziness is a virtue.

Requirements

Having a scripted deployment process means that the steps to deploy your code will be the same no matter who has the responsibility. Keeping a repo with your deployment scripts means the process is documented and can be critiqued and iterated upon.

We’re using Fabric because I am familiar with it. By all means, use Capistrano or some other deployment tool. Write a few shell scripts if that’s what you’re comfortable with. Do what you can to put the software to work for you.

A sound deployment strategy meets these criteria:

Extensibility

Want to deploy via git or sftp? Deploy a specific branch? Want to minify and compress assets before deployment? Maybe tag a commit for rollback purposes? Your deployment strategy should be extensible enough to accommodate these things and require little to no input from you. Write a script once and put it to work.

$ fab staging branch:exciting_new_feature deploy

Push button

Type the deployment command into your shell and hit enter.

$ fab staging master deploy

Rollback

If something goes wrong, issue another command to revert to a previous state and deploy.

$ fab staging rollback deploy

Fabric, git-ftp and WPEngine

Fabric is a wonderful Python library that allows you to script away application deployments and remote system administration tasks. It provides a way to wrap up what would otherwise be complex git commands/workflows in simple, easy to remember, fab commands.

Some of the things our fabfile is set up to handle include:

  • Use git-ftp to deploy files to WP Engine via sftp.
  • Check the commit hash of currently-deployed code and automatically tag it is as a rollback point.
  • Allow us to checkout and deploy a specific branch to a specific environment (i.e. master or stable to staging or production).

Why use git-ftp? In our experience, git deployment for WP Engine has been difficult to use and unreliable. Also, WP Engine requires an entire WordPress install as the basis for your repository, which isn’t how most of our repos are structured. Git-ftp allows us to work around these issues.

However, if we want to move to a git push-based deployment strategy or expand our toolkit to work with environments outside of WP Engine, adjusting or adding to our fabfile is trivial.

Usage

If you want to use our deployment tools with your project, you can follow the instructions in the README included in the repo. The README holds all the details regarding software prerequisites and how to install them.

If you’re already familiar with Python, Fabric and have your dev environment set up, you can find the “quick start” steps below.

These tools were meant to be added as a submodule in your project repo. This is based on the way Ryan Mark structured the Chicago Tribune’s deploy tools. To start:

$ git submodule add https://github.com/INN/deploy-tools.git tools

Then copy the files from tools/examples to the root of your project:

$ cp -Rf tools/examples/* ./

Finally, edit `fabfile.py` to use your WPEngine host, username and password:

# Environments
def production():
"""
Work on production environment
"""
env.settings = 'production'
env.hosts = [‘mywpinstall.wpengine.com’, ]
env.user = ‘mywpinstallusername’
env.password = ‘mywpinstallpassword’

After that, add and commit your changes. At this point, you should be able to deploy:

$ fab staging master deploy

If you want to perform a dry run beforehand to see exactly what files will be transferred:

$ fab staging master dry_run deploy

If you want to see a list of all available commands:

$ fab -l

Available commands:

branch                Work on any specified branch.
deploy                Deploy local copy of repository to target environment.
dry_run               Don't transfer files, just output what would happen during a real deployment.
master                Work on development branch.
path                  Specify the project's path on remote server.
production            Work on production environment
rollback              Deploy the most recent rollback point.
stable                Work on stable branch.
staging               Work on staging environment
verify_prerequisites  Checks to make sure you have curl (with ssh) and git-ftp installed, installs them if you do not.

Todos

Future plans include adding commands to handle asset minification and compression.

If you'd like to contribute, you can fork the code here.

How To Use GitHub Wikis For Collaborative Documentation

This week I've been updating the documentation for INN's Largo WordPress theme. The documentation previously lived on the project website but we're now adding a wiki attached to the INN/Largo repository on GitHub.

In this post I'll use the Largo wiki as an example to show you how to setup a Github wiki for your project.

Setup

GitHub wikis are themselves git repositories.1 This means you can keep track of changes to the wiki and accept issues and pull requests to a repository made to contain the wiki.

To allow contributors outside of our team to submit pull requests and issues to the wiki, it makes sense to set it up as a separate repository. When the project updates, we'll push updates from the wiki repository to the wiki on the main repository for the project.

For our purposes, the container repository for the wiki is called Largo-docs.

These are the remotes I have for Largo-docs:

$ git remote -v
origin	git@github.com:INN/Largo-docs.git (fetch)
origin	git@github.com:INN/Largo-docs.git (push)
wiki	git@github.com:INN/Largo.wiki.git (fetch)
wiki	git@github.com:INN/Largo.wiki.git (push)

The first remote there, origin, is the container repository for the wiki content (Largo-docs). The second is the wiki that's attached to the main Largo theme repo.

On GitHub, the URIs for project wikis insert .wiki between projectname and .git.

GitHub project wikis are ‘magical’ repositories that are associated with your project, but are not part of the project repository. When you push to them, the wiki is rebuilt with the new content automatically. If you use GitHub pages, it’s very similar.

Since Largo-docs is just another GitHub repository, you can provide users a link to the repository’s issues page, where they can give you suggestions and pull requests. If you want to allow people to contribute to the wiki without allowing people to directly edit the wiki, this is the way to do it.

When it comes time to publish new content to the wiki associated with the main theme repository, I make sure I'm on the master branch of the Largo-docs repository and then I push to the remote I set up for the wiki on the main Largo repository.

It's as simple as:

git checkout origin/master
git push -u wiki master

Organizing the Wiki Repository

Keeping the wiki in a separate repository also makes organization easier.

By default, GitHub wikis are flat, with no hierarchy. Inside a repository, you can create folders and place individual wiki pages in them.

screenshot

These pages are simply separate files, where the filename becomes the page name. For example, example-filename_here.md becomes “example filename_here” - use capitalization and dashes to create proper article titles.

The folder structure isn't reflected when GitHub generates the wiki, but it's great for your own organization.

If you want to structure the wiki, with some posts being parents to others, you can create a table of contents for the wiki and put it in a file named _Sidebar.md. The underscore is important.

screenshot-2

Create the hierarchy with an ordered or unordered list, and use horizontal rules as separators. Within posts, use Gollum syntax to link between pages.

Authoring and Editing

GitHub doesn't use straight Markdown for wikis, though. Wikis can use nine different markup languages for posts, with Gollum syntax used for internal links and images.

Mixing Gollum and Markdown markup leads to some interesting formatting, but nothing deal-breaking. In the container repository, GitHub will only render GitHub-Flavored Markdown (GFM). The Gollum-style inter-page links and image links will be ignored, leading to situations like this in the container repo:

This is what happens when you mix Gollum link markup and Markdown in a page: GitHub only renders the Markdown.
This is what happens when you mix Gollum link markup and Markdown in a page: GitHub only renders the Markdown.

Not pretty, but hey, it works!

If you're looking to document your project in a way that others can contribute to, but you don't necessarily want to open wiki editing to everyone, this is a great way to do it!

And of course you're welcome to contribute and help improve our documentation at https://github.com/INN/Largo-docs.


1: So are GitHub Gists, incidentally. And since May 1, 2014, you can use GFM task lists in wikis.

Introducing the INN Toolbox

If you've ever found yourself wishing for a list of reporting, data and visualization resources among INN members, today is your lucky day! We are happy to bring you the INN Toolbox, a collection of searchable databases, Github repos, APIs, embeddable widgets and more that can help with reporting and online presentation.

Use our searchable database to find tools such as:

  • Are these temperatures normal? Code available on Github from MinnPost that adds context to the temperature in your area by calculating how far above/below average your area is for the day, week, month and season. Updates every hour.
  • Barking Owl. A scalable web crawler intended to be used to find specific document types such as PDFs. From the Rochester Hacks and Hackers group that works closely with INN member Innovation Trail.
  • Influence Explorer. A collaboration among INN members Sunlight Foundation, National Institute for Money in State Politics and the Center for Responsive Politics, Influence Explorer connects the dots of political contributions on the federal and state level allowing you to track influence by lawmaker, company or prominent individual.

The INN Toolbox will be continually updated, and we'd love for you to contribute. There is an online form to add resources from your newsroom or tools that you find helpful.

You can visit the INN Toolbox here.