I'm creating a MS Word document (and will probably convert it to PDF later on) for a visually impaired programming student.

I'm following all the guidelines about text semantics, like correctly using headers, paragraph, tables, avoiding blank lines, etc. But I don't know what to do when it comes to code examples. I'm particularly using Python for this document, so not only there are code snippets but also interpreter examples, including the ">>>" symbols. What's the best way to add these in my document? Should I enclose these examples in a table containing just one cell, and then adding a title to the table along the lines of "this is a code example:"? Should I add line numbers? Any other markup that I should add?

2 Answers 2


I know this is old but this is the top result when searching for code block accessibility so I thought I'd cover the screen reader portion of this question since there was never a satisfying solution.

For my use case we used a standard code block with numbering and preserved spaces and tabs, then to cover the screen reader use case we used a visually hidden phonetic version similar to below.

<pre aria-hidden="true"><code>age = 10
if age != 10
    print ("It's not 10)</code></pre>
<span class="screen-reader-text">age space equal sign space 1 0. Hard Return. If space age space exclamation point equal sign space 1 0. etc etc </span>

You can use any visual hiding technique you like that works for you. We just used the screen-reader-text class from wordpress.

This may or may not work for your use case, but it worked for us so I thought I'd put it out there.


You can create a new paragraph style with a distinct background, and put the code inside. To improve readability, consider highlighting the syntax of the program, so it's easier to see e.g. what is a function and what is a text string.

enter image description here

Using Listing #. Description is a common way of numbering code examples in documents. If you will have multiple code listings in many chapters, consider including chapter number in them, e.g. Listing 3.11. Using for loop.

If there's another type of listing you need to add (interpreter examples?), you can make another paragraph style with different background color. As long as you keep the contrast high and colors are visibly different, it should work and be readable for all students.

  • Thanks! And would this also work for screen readers? I'm worried about them properly interpreting and reading the code examples.
    – Floella
    Commented Mar 20, 2016 at 16:51
  • 1
    In this case it would be better to put "Listing #" above the code block, so it's clear when the code starts (and maybe something like "End of code listing" at the end?). Still, I'm not sure how understandable a screen reader's take on code would be. Code isn't composed of full sentences, and screen reader might be confused at lines that don't end with full stops.
    – fri
    Commented Mar 20, 2016 at 17:01
  • 1
    @Anarelle If I remember correctly Python is very dependent on indentation amount, I doubt any screenreaders will read "three blank spaces print 'foo'", etc. Also characters such as semi-colons will likely be ignored as they aren't spoken in natural language. There are likely developer plugins you will have to instruct users to download in order to verbalize code.
    – DasBeasto
    Commented Mar 22, 2016 at 15:48

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.