Skip to content.
Table of Contents

Contributing Guidelines

Want to help? Here's how.

Please be sure to check our Code of Conduct and Content Style Guide before contributing. Questions or concerns about contributing can be addressed in the site's Issue Tracker.

About this site

Following are guidelines for submitting content for our site. Instructions on how to get the site running locally on your computer can be found in the README.

Submitting content

In the spirit of Open Source, The A11Y Project tries to only promote content that is free, or has a low barrier to entry.

Content style guide

The A11Y Project has a Content Style Guide to help our content have a consistent voice and tone. Please familiarize yourself with it before writing content for us.

Posts

Pitching

Have an idea for a post? Great! We'd love to know what you want to contribute!

  1. Search our open GitHub Issues to make sure someone hasn't claimed the post already.
  2. Claim a post by starting a new Issue with "Post: Your title" as the Issue title. This will help us keep track of who is working on what. The final, published title can be different from the Issue name.

We also have a list of posts we'd love to see written!

Writing

Posts are written using Markdown, using a special formatting technique called front matter. Eleventy uses front matter information to create things like author attribution, categories, and page layout.

To get started writing a post, create a feature branch and create a new Markdown file in the posts directory. The Markdown's file name should reflect the intended publishing date and the title of the post. For example, a post about accessible typography may have a filename along the lines of accessible-typography.md.

Copying an existing post, then updating its filename and front matter to match your post can be an easy way to help ensure everything is formatted properly.

If you would like to write an post but do not feel comfortable working in Markdown or with GitHub, please contact us and we can work something out.

Submitting

Once you are satisfied with your post's content, submit a Pull Request so it can be reviewed. Reviews will be conducted using GitHub's review tools. Project maintainers may request additional updates for clarification or technical accuracy.

Be sure to also add yourself to authors.json so you can get credit for your work!

Once both the project maintainers and author are satisfied with the post, it will be merged by a project maintainer and published automatically. We will also notify you that publication has occurred.

Compensation

Each published post will receive $75 USD. We will also:

Payment is coordinated via email, using PayPal, Venmo, or Square Cash. We no longer support bank transfers due to attempts at scamming.

Translation

The A11Y Project does not currently support translations of our content, either on or offsite.

Creating, updating, and maintaining accurate translations require a level of investment and resources we cannot currently provide. This would endanger the quality of our content and potentially risk creating access barriers.

If you are prepared to make a long-term commitment to supporting translated content on our site, please contact us.

Resources

Did you create or find a great accessibility-related resource that you think other people would find useful? Add it to the Resources file under the appropriate category, or contact us.

Please be sure to include the resource's title, description, and a URL where it can be accessed.

Social media posts

We share links about accessibility, inclusivity, design, and development on Twitter and LinkedIn. If you would like to submit a link for sharing, please contact us and include the link in your message.

Evaluation

Process

When you submit content to us, one or more of The A11Y Project maintainers will review it and provide feedback, if it is necessary. These reviews happen on GitHub or in email.

When we evaluate suggested content, we consider the following things:

A maintainer may reach out to someone submitting content to request clarification or further information.

Rejection

Project maintainers may elect to not accept your submission if they feel it is not in line with the site's goals. This will be handled on a case-by-case basis.

Unacceptable content

The following content is not allowed on the website:

Promotions, partnership deals, and SEO scams

We are not interested in quid pro quo schemes to boost your site's SEO ranking. We are also not interested in backlink, partnership, and affiliate linking programs.

Plagiarism

The A11Y Project does not condone plagiarism. We check submitted content for stolen phrasing and assets when submitted. People found plagiarizing content will be asked to stop contributing to the website.

Git and GitHub

The A11Y Project is an Open Source project. It uses Git and GitHub to handle publishing new content and features, as well as coordinating maintenance.

People working on more sophisticated aspects of the site (new features, bug fixes, etc.) are expected to have at least some familiarity with version control, GitHub's key functionality, and using feature branches to work locally.

If you are looking for a place to get started learning about Git and contributing to an Open Source project, Egghead.io offers a great introductory course.

Forking

To submit updates and changes to The A11Y Project, you will first need to Fork the repository.

Forking will create a copy of the repository on your GitHub account. This will allow you to make changes on your copy and suggest incorporating them into The A11Y Project's repository in the form of a Pull Request.

If you do not plan on working on The A11Y Project for an extended period of time you can delete your Fork of the repository after your Pull Request has been merged without endangering our copy.

Build process

This project uses Eleventy to convert project files into a website that a browser can read and display. You'll need to make sure you've run all the commands in our README to get Eleventy working.

Tatiana Mac has a great beginner's guide to Eleventy, if you are looking for a good introduction.

Any changes you save will cause the local version of the site to recompile. The browser tab that has your local instance of the site will automatically refresh, allowing you to preview your edits.

Important branches

main is the production branch. This is the live website.

If you have a feature request, we suggest first filing an Issue to discuss it (please read how to report an issue first). Once that feature has been approved you can start coding! Create a new feature branch from main, and name it something that references the feature you'll be working on. For example a feature to increase the site's type size could be: increase-font-size.

A list of all active branches is available.

Editing files

This site uses specific kinds of files to help run the site efficiently. Eleventy will take these files and compile them into HTML, CSS, and other browser-friendly code.

Please make all edits in these files, and not the compiled code. If you edit the compiled code it will be overwritten the next time any file is saved and all your hard work will be lost!

Some of the main files this site uses are:

Markdown

Markdown is a lightweight markup language that makes writing easier. We use it mainly to organize our blog posts. It uses .md files and compiles into HTML.

Nunjucks

Nunjucks is a templating language for HTML that uses JavaScript. We use it to create the templates used to build the site. It uses .njk files and compiles into HTML.

Sass

Syntactically Awesome Style Sheets (Sass) is an extension of the CSS language that adds many helpful features. Using it helps keep our site's visual presentation consistent. It uses .scss files and compiles into CSS.

JSON

JavaScript Object Notation (JSON) is a human-readable way to store structured data. We use it to store information such as resources and commonly-repeated information. It uses .json files.

SVG

Scalable Vector Graphics (SVG) is a vector-based image format that makes crisp images with a small file size. It uses the .svg file format and can be either declared inline, or linked to as an image.

YAML

YAML Ain't Markup Language (YAML) is a human-readable markup language that is good for writing structured data. This structured data is used specifically for posts and Eleventy page templates.

Submitting new features

New features typically represent significant changes to the website. We ask that before you begin work on adding functionality or features that you bring up your proposed changes as a GitHub Issue first.

This helps the site maintainers anticipate and plan for incorporating large-scale changes, how they'll affect the website, as well as discuss potential accessibility implications.

Fixing things

Reporting Issues

Have you noticed something inaccurate or inaccessible? You can help make it better!

  1. File an Issue.
  2. Preface your Issue title as an:
    • Inaccuracy for incorrect or inaccurate information (e.g. "Inaccuracy: Visually hidden CSS missing property declaration").
    • Inaccessibility for an accessibility issue (e.g. "Inaccessibility: Low contrast link color").
    • Bug for site issues (e.g. "Bug: Link at archive not working").

Issues are not to be used for free accessibility help. Project maintainers may close reported Issues at their discretion.

Submitting Pull Requests

Creating a descriptive Issue and assigning it to yourself before you send your Pull Request will help get it accepted. Doing so will provide a better understanding of what your request entails and why it was made. It also helps to link the Issue to the Pull Request and vice-versa (eg. "This Pull Request addresses Issue 213").

Project maintainers may reject Pull Requests at their discretion.

When submitting your Pull Request, please include the text "closes" or "fixes" and then the issue number (e.g. "Fixes #101."). This will help us automatically close the issue upon merging the Pull Request.

Stale Issues and Pull Requests

Project maintainers will close Issues and Pull Requests if they become stale, leaving a note for the author as to why. This keeps our Issue tracker and code work clean and up-to-date, and helps project maintainers focus their attention where it is needed.

Stale Issues

An Issue is considered to be in a "stale" state when any of the following conditions are met:

  1. The last comment was made over three months ago.
  2. There has been no activity since.
  3. Someone has attempted to address the Issue, with no followup participation from the author.

Stale Pull Requests

A Pull Request (PR) is considered to be in a "stale" state when the following conditions are met:

  1. The last comment was made over three months ago.
  2. There has been no activity since.
  3. Someone has attempted to move the PR along with no followup from the author.

Labels

Labels allow the project maintainers to quickly sort and filter site Issues and Pull Requests. They will be added and removed as needed.

Updating Posts

When updating posts, leave the original publish date and author as-is. Add the following to the front matter:

updated_by: editor_name
last_updated: yyyy-mm-dd

Content we no longer support

Following is content we’ve removed from the website and no longer support:

Events

The A11Y Project used to list webinars, regional events, and meetups. We no longer support this feature. If you are interested in finding an accessibility-related group near you, please check our Meetups section in Resources.

Patterns

The A11Y Project used to list code patterns. We no longer support this feature. If you are interested in learning about accessible implementations of common User Interface elements, please consult the WAI-ARIA Authoring Practices.

Who to follow

The A11Y Project used to list people to follow in the digital accessibility space. We no longer support this feature. Bruno Pulis maintains a list of notable people, companies and organizations, and meetups that contribute to digital accessibility and open standards.

License

By contributing your code and content, you agree to license your contribution under the terms of the APLv2.