Our ideal of technical writing is that of a clear documentation that does not generate misunderstandings and provides simplified and easy to understand instructions.

The content of technical documentation is not the only thing to consider when speaking of clear and straightforward information. Accessibility is another crucial aspect to deal with to make sure it is available to everyone. In fact, we should always keep in mind that users can access information through different means and technical authors should always try to reach the widest audience when writing.

Below you can find some guidelines that we have adopted as part of our authoring checklists to create more accessible texts.

Tables and images

Tables and images are considered to be visual elements but they are fundamental parts in the document structure, therefore we should make sure they are fully accessible by including them in the technical documentation in a smart and optimized way.

Text

Screen readers cannot vocalize text inserted into images as part of graphics itself. For this reason, it is essential not to insert text in images, photos and graphics. This best practice can be adopted in the translation process as well, since CAT tools are not able to read texts contained in images either and texts should therefore be extracted for translation. 

Alt text

Alt text is text that is put in the table or image properties. This text can be correctly vocalized by screen readers to describe the content of tables and images. It should not only describe the look but also the intent of visual elements.

Alt text also helps to properly index images in online documentation and will be shown even when the visual elements that it describes are not correctly loaded.

Alignment

Screen readers move across a file like a cursor or our eyes do: left-to-right and top-to-bottom. Images and tables should, therefore, be aligned to the left of the text. Other types of alignment can ‘break up’ sentences read by screen readers, making them incomprehensible.

Merged cells and headings

It is very common to use merged cells in tables in order to make them more visually appealing. However, screen readers are not able to correctly vocalize them and to identify their intent. For this reason, it is advisable to avoid merged cells to make information accessible.

With regards to table heading, when a table breaks across pages, the row containing column header should be set as repeatable at top of each page in the table properties to allow screen readers to interpret it correctly.

Text and documents formatting

Formatting is both aesthetic and functional because it allows us to correctly understand the document structure. Make sure to use bold, italics and underlines consistently throughout the document and to create numbered and bulleted lists using the specific function instead of using random decorative characters.

If the software allows you to define the correct language in the document, it is worth doing it.

Titles and headings

A portion of text will not turn into a title or heading by simply using bold or a larger font size. Screen readers and speech synthesisers can recognise metadata used in heading styles and vocalize that information. 

Talking about formatting in general, titles and headings should be clearly visible and spaced so that they can be distinguished from paragraph texts. Authors should not use font size smaller than 11 to make sure it is legible by the naked eye and text should be aligned left.

Colours

Technical documentation accessibility is determined by colour choices as well. We should keep in mind that colour perception might be different among users and for that reason we should use colours that provide maximum contrast between the content and the background so that text and visual elements can be legible to everyone.

Also remember that green and red are often confused by people with colour vision deficiency, therefore they should be avoided, especially when used as ‘good’ and ‘bad’ indicators.

The aim of effective documentation is to be understood without difficulties: accessibility is a key aspect in our authoring process to create user-friendly texts.