This short guide goes over several aspects of accessibility to keep in mind when writing or editing posts on the Codidact network. There are many different disabilities out there, and these tips cover accessibility for many of them, such as people using screen readers, keyboard users, colorblind users, and people with cognitive disabilities.


Table of Contents


Formatting

Headings

Headings are used to separate sections of information. Each heading should give you a decent indication of what you can expect in that section. (As an example, the heading "headings" before this section is a good hint that this section is about headings.)

Screen readers and similar can jump from heading to heading (including describing what level of heading), so keep that in mind when choosing headings for your posts.


Examples

A good heading order follows the logical layout of the page, without skipping over levels, consistently uses the same level headings for sections at the same level, and only uses headings for actual heading content.

// Example of a good heading order
<h1>Question title (automatically provided)<h1>
<h2>Answer section 1</h2>
<h3>Answer sub-section 1a</h3>
<h3>Answer sub-section 1b</h3>
<h2>Answer section 2</h2>
<h3>Answer sub-section 2a</h3>
<h3>Answer sub-section 2b</h3>
<h4>Answer sub-sub-section 2b.1</h4>
<h4>Answer sub-sub-section 2b.2</h4>
<h2>Answer section 3</h2>

The heading order above shows an answer that doesn't use a top-level heading (<h1>), since there's already one on the page - the question title. It uses <h2> to differentiate its high-level sections. It then uses <h3> for the sub-sections, and when it's necessary to have a sub-sub-section, it uses <h4>.

A bad heading order would skip levels, use headings for non-heading content, or unnecessarily over-use top-level headings.

// Example of a bad heading order
<h1>Question title (automatically provided)</h1>
<h1>Answer summary (actual content)</h1>
<h3>Answer section 1</h3>
<h5>Answer sub-section 1a</h5>
<h4>Answer sub-section 1b</h4>
<h2>Answer section 2</h2>
<h4>Notes</h4>
<h1>Thank you for reading!</h1>

This bad example uses <h1> twice in the answer, despite there already being a top-level heading as the question title. It uses an <h1> heading for the answer summary, using a heading for non-heading content. It then uses wildly inconsistent heading levels for its different sections and sub-sections, and skips levels of headings (such as moving directly from <h3> to <h5>).


Emphasized text

Emphasized text, such as bold or italics, is good for calling attention to key words or sentences. However, if it's overused, it ends up defeating its own purpose and making a post more difficult to read instead of clearer.

Code markup

Text size

Codidact has integrated footnotes available, so you should avoid using sub- and superscript for footnotes; use the dedicated Markdown instead.

Tables

Images

Alternative (alt) text

As a general way of making sure your alt text is appropriate, consider if the information present in the post would change at all if the image was replaced entirely with the alt text. If the information would stay the same, you're good to go.

Decorative images

Note that this is blank, not missing. From a coding perspective, this means setting its alt attribute to ="", not leaving out the alt attribute.

In general, you should avoid including images that don't serve any specific purpose or that are just decorative in your post.
If you find yourself including a decorative image, make sure that it's not formatted as a link, leaving only the embedded image, and to set the alt text to be blank.

Stable resource (local images)

In order to avoid the possibility of dead images, and ensure that that post remains stable for as long as possible, you should avoid using an external image hosting service. Instead, use the built-in image uploader for the Codidact Network. This means that the image is stored on our own servers instead of depending on someone else.


Examples

Let's take the following snippet of a post for our example:

When you go to edit a post, you now have the option to check the "redact" button:

Checkbox to select "redact": Redact original content by hiding the previous versions from history?
(Source: "What should I do when I come across PII in a post?" by Mithical on Codidact Meta, licensed under CC BY-SA-NC 4.0)

In this example, the image is being used to illustrate the new button and what it does. That information needs to be presented in the alt text as well, which the current alt text does:

![Checkbox to select "redact": Redact original content by hiding the previous versions from history?](https://meta.codidact.com/uploads/qwvy25mvolpdjabhknuujzjncbpm)

This is short and to the point. It tells anybody who can't see the image what information is shown with the checkbox, which is why the screenshot was included.

A bad example would be leaving out the alt text, having overly long alt text, or relying on an external image hosting service:

![](https://i.imgur.com/XtjJxjF.jpg) 

![A screenshot of two different sections that you see when editing a post. One says "Edit Comment" with a blank text box, where you can input an edit comment that will show up in the revision history for that post. The other says "Redact", and it has text with an unchecked checkbox. It has the text "Redact original content by hiding the previous revisions from history?" Below those are two buttons. One is blue and says "Save Post in Q&A". The other is gray and says "Cancel".](https://meta.codidact.com/uploads/qwvy25mvolpdjabhknuujzjncbpm)

In the first bad example, there is both no alt text and it relies on an external image service. There is no information presented to anyone who can't see the image, and there's the risk that the image will go dead even for people who can see it.
In the second bad example, the alt text is too long. It has information that's not present in the image itself, such as information about the edit comment appearing in the revision history, and describes information that's not relevant to the purpose of the screenshot - which is simply to show what you're presented with when you go to redact a post.


Don't rely solely on color

When your image uses colors to indicate a difference between things - such as on a chart or graph - you should also use a different method of differentiating, such as an icon or different shape. Also avoid using colors that are known to be a problem for colorblind users (such as red/green).

Contrast

Avoid colors that are too close to each other, especially for text on a background color. As a simple way of testing, take a glance at the image in sunlight - can you still make it out?

Animations

We don't currently support any way to disable or pause animations in posts, so avoid using animations where possible. In particular, make sure to avoid flashing content (especially anything flashing more than three times a second - don't do that!). Flashing content can cause seizures, and looping animations can be distracting for everyone, but especially for people with some cognitive disabilities.

Images of text

Quoting

Stable resource (Web Archive)

While not required by any standard that I'm aware of, I'd encourage you to take steps to make sure that any resource you link to remains stable by archiving it in the Web Archive when you link to it. (This is similar to what Wikipedia does; sources used in articles are almost always archived so that a backup exists.)

Making your posts understandable

Vocabulary

This should not come at the expense of precision or accuracy, though; keep your audience in mind. If you are writing for a highly specialized or technical audience, you shouldn't necessary shy away from using the relevant terminology; but if you're writing for everyone, using relatively simple terms is often a good idea.

Define acronyms and specialized terms

This applies to specialized terms, jargon, and words in other languages as well. The first time you use a specialized term, define what it means or translate it.

Paragraph and sentence breaks


And those are the top tips for making your post accessible! Remember that accessibility is an ongoing process, so don't feel too bad if not all of your posts meet these guidelines. They can always be edited later, and the important thing is to keep accessibility in mind as you go forwards writing and editing posts.