Advertisement
Case Studies

How They Did It: The Accessibility Project

by

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.

a11project


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

a11-contributors

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.

a11-githubpages

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

a11-jekyll

Jekyll uses YAML front-matter configuration settings to help generate pages/posts locally. These posts and pages come out as static HTML, JavaScript, and CSS files. (Check out more about Jekyll here: Jekyll usage wiki on GitHub.) If you want to contribute to The Accessibility Project, this is the best way to create a new post.

  1. Clone the repository
  2. Use bundle to install all dependencies. The Gemfile specifies three gems that will be installed. (Also, you'll need Bundler for bundle to work.)
  3. 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.
  4. Use rake post title="Something Interesting About Accessibility" to create a post.
  5. 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

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.

  1. Write out your brilliant idea in a GitHub Gist or Clap
  2. Reference that idea in an issue on the a11yproject.com issues page
  3. Discuss the idea with others via the GitHub issue
  4. Refine the content, and create a post via Jekyll rake post title="your title" in your local copy of the repository
  5. Run rake server and visit http://localhost:4000 to take a look at your post (and the rest of the site)
  6. Run rake check to make sure you didn't break anything. (If you did, that's a topic for the comments thread.)
  7. 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?

  1. File a descriptive issue
  2. Assign yourself
  3. Build the skin
  4. Submit a pull request attached to the issue
  5. 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.

a11-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?

Related Posts
  • Web Design
    HTML/CSS
    Why I Choose Stylus (And You Should Too)Stylus thumb
    The world of front end web development has been steadily increasing its uptake of what we call "CSS Preprocessors", which extend the functionality of regular CSS. Arguably the two most well known, with the greatest user base, are LESS and Sass/SCSS. However there is a third preprocessor that hasn't received quite as much attention, and that's Stylus.Read More…
  • Code
    Tools & Tips
    Coding in the CloudCoding in cloud retina preview
    The Internet has allowed us to work anywhere we want, giving us tremendous flexibility in choosing where we'd like to plant ourselves to build the next great app. Not being tied to an office desk has been a blessing to many who cherish the ability to work in varying environments and draw inspiration from their surroundings. But for the most part, we've needed to have a full-blown development machine to make this happen. What if we could leverage the cloud as a development environment itself, freeing us up to choose from a variety of devices to accomplish the same thing. That's what we'll explore in this article.Read More…
  • Code
    Tools & Tips
    How to Collaborate On GitHubGithub collab retina preview
    If you don't already know, GitHub is an incredibly effective way to collaborate on development projects. Providing a place for anyone with an internet connection to have an avenue where they can share code with the world for free (not to mention the robust supporting tools for source inspection and easy viewing of commit histories). GitHub has been adopted by many large open-source projects as their primary home for collaboration and contribution. But how do you join in and contribute to a project? Sure, you know how to use Git to track changes to files and push those files to a server. But there are major benefits to getting involved in larger open-source projects, and GitHub is arguably the best place to start. Today, we will discuss a few rules of the road for collaborating on open source projects, and give you the knowledge and intuition you will need to get involved.Read More…
  • Web Design
    Applications and Tools
    Getting to Know GitHub Pages: Static Project Pages, FastGithub pages preview retina
    Let's talk about GitHub Pages; what they are and how you can use the service in minutes to deploy static pages for free. Let's get started!Read More…
  • Web Design
    Applications and Tools
    Getting Started with OctopressOctopress preview
    Octopress is a static blogging framework built on top of Jekyll. It uses scripts to build static files to be deployed to a server.Read More…
  • Code
    General
    Team Collaboration With GitHubGithub team preview
    GitHub has become the corner stone for all things open source software. Developers love it, collaborate on it and are constantly building awesome projects through it. Apart from hosting our code, GitHub's main attraction is using it as a collaborative tool. In this tutorial, let's explore some of the most useful GitHub features, especially for working in teams, making it all the more efficient, productive and, most importantly, fun!Read More…