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.

The People

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.

GitHub

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

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

Use bundle to install all dependencies. The Gemfile specifies three gems that will be installed. (Also, you'll need Bundler for bundle to work.)

Use rake -T to 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.

Use rake post title="Something Interesting About Accessibility" to create a post.

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.

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.

The CodeKit config file is used to generate settings for CodeKit, which compiles the SASS files for the project. This config helps maintain conformity between different users. You might recognize the filetype (JSON) - the file is a valid JavaScript object. JSON is also used for many other environment configurations.

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.

Refine the content, and create a post via Jekyll rake post title="your title" in your local copy of the repository

Run rake server and visit http://localhost:4000 to take a look at your post (and the rest of the site)

Run rake check to 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.

Synergy

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.

SASS+Compass Only

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.

While some may consider this a limitation, it serves a purpose. First, it makes the codebase less complex; if the project tried to support vanilla CSS, LESS, and SASS, the result would entail major dependency headaches. It would also require contributors to update both LESS and SASS files - something that is much less likely to encourage involvement. Finally, those who are driven to contribute and also have the skills or quality content to contribute will either already know SASS, or will have a means to learn it. While this seems exclusive, we must also consider that this, at some point, is the case with any technology; those who do not know (and aren't willing to learn) how to integrate their JavaScript with jQuery simply cannot write jQuery plugins.

Conclusion

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?