3

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?

1

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 Mar 20 '16 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 Mar 20 '16 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 Mar 22 '16 at 15:48

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

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