robmc.github.io/style-guide.html at master · robmc/robmc.github.io · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
<!DOCTYPE html>
<html lang="en">
	<head>
		<title>Inclusive Style Guide</title>
		<style type="text/css">
			h1 {
				text-align: center;
			}
		</style>
	</head>
	<body>
		<h1>Accessible/Inclusive Style Guide</h1>
		<p>The intent of this document is to serve as a reminder for authoring accessible/inclusive documentation.</p>
		<h2>Term Definitions</h2>
		<p>Technical writing often uses abbreviations. These can be for agency names, software brands, code techniques, etc. It is important when authoring documentation never to assume that the user understands abbreviations. The first time the term is introduced within your writing, you must use the long form of the term followed by the abbreviation in parenthesis. This ensures the user is informed of the abbreviation's meaning.</p>
		<h2>Person-first Language</h2>
		Always put the person first, not their disability. We favor "people who are blind" opposed to "blind people" because it leads with the individual and does not define the person by their disability.
		<ul>
			<li><strong>DO</strong> say things like "Users navigating with screen readers cannot complete the form due to a lack of explicit labels." &#9989;</li>
			<li><strong>DO NOT</strong> say things like "Screen reader users cannot complete the form due to a lack of explicit labels." &#10060;</li>
		</ul>
		<h2>Use appropriate/modern terminology</h2>
		Many terms for People with Disabilities (PWD) are outdated. There are terms I have encountered in my career that are outdated and should not be used.
		<table>
			<thead>
				<tr>
					<th>Good Examples</th>
					<th>Bad Examples</th>
				</tr>
			</thead>
			<tr>
				<td>People with disabilities</td>
				<td>The disabled</td>
			</tr>
			<tr>
				<td>Disabled</td>
				<td>Handicapped/crippled</td>
			</tr>
			<tr>
				<td>Person with a disability</td>
				<td>"Normal" or able-bodied</td>
			</tr>
			<tr>
				<td>Cognitive or Mental Disability</td>
				<td>Retarded</td>
			</tr>
			<tr>
				<td>People with visual disabilities</td>
				<td>The blind</td>
			</tr>
		</table>
		<h2>Reading Level</h2>
		<p> WCAG has a AAA-level requierement for <a href="https://www.w3.org/TR/UNDERSTANDING-WCAG20/meaning-supplements.html">SC 3.1.5 Reading Level</a>. Most organizations do not adhere to AAA but only meet A and AA requirements instead. Still, it's important to understand how reading levels affect the end user(s).</p>
		<p>When content is difficult to understand or when too many complex words or phrases are used, users may stop interacting with your content due to not understanding it. Plain language that is easy to understand is recommended where applicable. This concept can be challenging when performing technical writing of complex concepts but should be considered when authoring content.</p>
		<footer>
			<a href="http://robertjmccaffery.com/examples.html">Back to Examples</a> | <a href="http://robertjmccaffery.com/">Home</a>
		</footer>
	</body>

</html>