How They Did It: The Accessibility Project
Perhaps you, or someone you know, has experienced the difficulties of computer interaction for the impaired. In general, operating systems and software suites have made provisions for accessibility for hearing-impaired audience, vision-impaired audience, and internationalization; however, the open web hasn't caught up as quickly. Many sites ignore accessibility completely.
Perhaps one of the reasons for this is that there arguably isn't a source of up-to-date, digestible content focused entirely on accessibility.
The Accessibility Project (a11yproject.com) is changing this. By offering an open platform (via GitHub), a11yproject is building a crowd-sourced, self-curating set of content that is digestible, up-to-date, and forgiving. (See their about page.)
The Accessibility Project is a great example of how technology can help support collaborative development. Anyone can contribute. The cost of support for this is nearly nothing, and management of the site is minimal, driven by the community.
There are a lot of people behind a11yproject, including Dennis Gaebel of Gray Ghost Visuals, Dave Rupert over at Paravel, Jamie Piper at Alliants, Mat Marquis and a slew of others. (Take a look at the contributors list of avatars at the bottom of the homepage.)
This is a group worth joining, and the awesome part is, you can do so by simply contributing!
So, how are they doing it?
The Accessibility Project is set up for remote, asynchronous collaboration. The site doesn't use a database, and requires no hosting provider. Here's how they do it.
The site is entirely hosted by GitHub via GitHub Pages. GitHub Pages allows GitHub users to publish static content, and serves that as a web page.
GitHub Pages is, in general, created to support projects and users, giving them a place to host documentation, examples, etcetera. The folks at GitHub have also made pages compatible with Jekyll.
Jekyll is the Ruby-gem based workhorse framework behind The Accessibility Project. Built by Tom Preston-Werner and others at GitHub, Jekyll is a static site generator that allows users to create posts and pages in Markdown or Textile (although a11y posts are only Markdown).
- Clone the repository
bundleto install all dependencies. The Gemfile specifies three gems that will be installed. (Also, you'll need Bundler for
rake -Tto list commands you can use that are specific to this project.
rake, or "Ruby make", is a tool that allows repetitive or automated tasks to be abstracted to a file within the working directory (called a Rakefile) and invoked via the command-line.
rake post title="Something Interesting About Accessibility"to create a post.
- Add your post via normal Git workflow (see below for some helpful tips for this specific project)
An even cooler feature of GitHub Pages: it will compile your Jekyll site for you, if you'd like.
A quick note: Why static?
Why would you want to go with a static site generator? There's a lot of reasons why this is a good answer to many development problems. First, static files are easy to serve. Basically any web server can serve static files. Beyond this, serving static files is generally incredibly fast and efficient.
Similarly, the overhead of serving static files is much lower on the server. Offloading the management of content to a local development environment reduces uncertainty and the necessity for a sysadmin-oriented environment.
Another good reason to go with a static site generator is security; static sites are infinitely less vulnerable to security issues like SQL injection than database-reliant sites. Lastly, most periodic-based content lends itself to static files already; the content isn't being generated by a data-driven algorithm or livestreamed data. Rather, it is text-based content that won't change (unless edits are manually made). The important distinction here is that the posts are manually created, and the layout around the content doesn't change dynamically. These are all signs that using static files is a good solution.
Explaining strange files: .rvmrc
RVM is a tool that manages multiple installs of the Ruby programming language. RVM uses
.rvmrc files to make sure the proper version of Ruby is selected to run for a given project. A helpful hint: any file that begins with a
. is most likely a configuration file; in particular, .*rc files, or "runtime configuration" files, generally are evaluated at the time of execution/runtime, usually just once.
Explaining strange files: codekit-config.json
GitHub Issues + Pull Requests
The "best modern web workflow" is an elusive topic, but a lot of people have recently published about the flexibility and usability of integrating feature-oriented development revolving around discussion with GitHub Issues and Pull Requests. (Check out Zach Holman's great Speaker Deck about the subject.) To file an issue, you simply go to a project and click on Issues, and explain the issue. The project owner can categorize your issue, and respond to it; if a patch or pull request fixes the issue, natural language can be used in the Git commit message to mark the issue as resolved. For instance, "Fixed issue #42". Then, you can submit a pull request referencing a specific commit; if that pull request gets accepted, that issue is marked as resolved.
But let's take a step back here, before we get in over our heads talking about Git workflows for hours on end.
The way The Accessibility Project uses GitHub is as a way to manage content, both in its pre-published stage and in its published stage. If you have an idea for an article, you can create it (either through a GitHub Gist or a Clap). Once this is done, filing an issue on the GitHub that references your Gist/Clap starts the conversation about your particular article. Finally, take the article from the Gist into a Jekyll-powered post. This involves a few simple terminal commands, a commit, and a pull request to resolve the issue you filed about that article. So, here are the basic steps.
- Write out your brilliant idea in a GitHub Gist or Clap
- Reference that idea in an issue on the a11yproject.com issues page
- Discuss the idea with others via the GitHub issue
- Refine the content, and create a post via Jekyll
rake post title="your title"in your local copy of the repository
rake serverand visit http://localhost:4000 to take a look at your post (and the rest of the site)
rake checkto make sure you didn't break anything. (If you did, that's a topic for the comments thread.)
- If everything is good to go, push up and submit a pull request referencing your post's commit; be sure to include "Fixes #42" in your commit message if your issue was #42.
If you aren't up to snuff on your Jekyll or Git/GitHub skills just yet, you can also ask for help in rolling your post into a commit. Comment on the post's associated Issue. Also, be sure to check out this screencast on our sibling Tuts+ site, NetTuts.
In case you haven't noticed, all of this content creation process revolves around linked conversation/content threads on GitHub. This provides a way to naturally combine a conversation with an associated action. This is a critical integration for any kind of collaboration.
More Nuts and Bolts
The site relies on a Sass/Compass port of Twitter Bootstrap, so there's nothing surprisingly innovative about the design of the site. However, it is also open for contributions and collaborations; Issues filed on GitHub are not only for collaborating on post ideas, but also for pointing out inaccuracies, inaccessibilities, and bugs. Even beyond this, Anyone is welcome to submit issues and pull requests to better the site in any way; think the site could use a new skin?
- File a descriptive issue
- Assign yourself
- Build the skin
- Submit a pull request attached to the issue
- Get famous*
*Getting famous is unrelated to submitting your pull request.
The Accessibility Project is exclusively built using SASS and Compass; if you want to submit any design changes, you must do so using SASS and Compass.
Open-source is an amazingly powerful tool. Using platforms like GitHub and tools like Jekyll make open-source shine. Communication integrated with working documents is essential to efficiently collaborate, especially if the work being done is in parallel to others doing similar work.
The Accessibility Project is a great example of all of these principles coming to fruition. With nearly forty top-notch contributors to date, it is a display of the power of open-source and the willingness of people to collaborate to make something great. The project incurs very little to no overhead for this site to exist.
What solutions can you create to solve problems efficiently? What tools do you use to support a workflow? How do you integrate collaboration, communication, and task flow?