00:00:00.080
I'm going to talk today about how to accessibility if you're mostly on the back end um and as a longtime rubyist
00:00:07.319
all my examples are in Ruby and so this is a good crowd for that so let's get
00:00:12.759
started um my name is Hillary St crowy I'm a senior a software engineer at Red Canary where a cyber security startup
00:00:19.800
based out of Denver um I'm a very neglectful Gardener I pretty much only plant native
00:00:26.480
perennials because they don't really need me uh and I'm the kind of person who
00:00:31.599
dresses up when I go to the Renaissance Fair every summer so this is from last summer uh I went as a fairy with very
00:00:39.000
anatomically incorrect wings but what do you do so uh what are we going to talk
00:00:44.719
about today uh first going to have a little bit of an intro um then we're going to talk about like what do we mean
00:00:49.760
by the word accessibility and we're going to get into some specifics with the code including apis and specs and then also
00:00:57.600
General practices and then we're going to do a quick wrap up so first why are
00:01:03.320
we here right why do backend devs even need to care about accessibility we typically think about like external users right so does our UI have good
00:01:10.400
color contrast can you navigate it with your keyboard things like that um but
00:01:16.040
there's also internal users right there's all of us and our co-workers so 160% of people globally have some kind
00:01:22.840
of disability 20% of people have dyslexia and 8% of men are colorblind
00:01:30.600
right and this isn't just older people I think sometimes we think oh as you get older you know you might have memory
00:01:36.600
issues or mobility issues one in 12 adults under 35 have a
00:01:43.360
disability so this means there's a strong chance at least one of your co-workers could benefit from
00:01:49.759
accessibility practices the best part too is that this isn't just about people who maybe have
00:01:56.000
different needs or disabilities accessibility improvements benefit everyone and we're going to take look at a couple of examples so who here uses
00:02:03.240
like an Alexa or Google home or something like that people want to just like put their hands in the whatever the
00:02:09.759
way you do it yeah see a couple okay so the First full text to speech
00:02:16.400
synthesizer was invented in 1976 to help the blind Community how many people listen to
00:02:24.239
audiobooks first one was recorded I thought this was really cool the first one was recorded in 1930 two on a record
00:02:33.080
by the American foundation for the Blind and how many people use an electric
00:02:38.599
toothbrush this one usually gets the most yeah right yeah those were invented
00:02:44.440
in 1954 for people with limited motor skills so even if you don't use one of
00:02:51.280
these right you almost certainly know someone who does who doesn't need it right it just makes our lives easier it
00:02:57.720
gives us gives us a benefit and even if some of these do have like more you know you might consider like a neutral impact
00:03:03.879
for most people adhering to accessibility standards is more and more commercially or legally required not
00:03:09.400
even just about doing the right thing so what do we mean by
00:03:15.920
accessibility right when we hear it we likely think about making things usable for people with disabilities but what is
00:03:22.519
a disability so this is what the US centers for dis Disease Control This Is
00:03:27.799
How They Define disability any condition of the body or mind that makes it more
00:03:34.239
difficult for someone to do certain activities and interact with the world around them so this is a very broad
00:03:40.519
definition and we're going to be kind of going at this definition unnecessarily like what constitutes a legal disability
00:03:46.239
we're going to take this this sort of wider perspective on it in this talk so what are some states that would fall
00:03:51.640
under you know benefiting from accessibility long-term disability so these are things like blindness ADHD
00:03:58.640
paralysis right these are kind of the things I think we default to when we think about disability there's also what
00:04:04.319
are considered temporary disabilities so you broke your arm you have pneumonia you were in a car accident and have
00:04:09.760
Whiplash right these are like states that we expect to change oh yeah someone
00:04:15.079
said poor bird it took me forever maybe I'm just a bad prompt engineer but it took me forever to get a a bird with a
00:04:23.360
broken arm who didn't have yet another Wing like they kept giving me three wings so the broken wing the regular
00:04:30.360
wing and then another Wing anyway uh you know and apart from kind of those temporary and more permanent
00:04:36.759
disabilities there are also experiences or conditions right going back to that definition from the CDC that can make
00:04:42.600
things more challenging so what are some examples of those you don't know any co-workers who have a different first
00:04:48.479
language than the rest of the team who are earlier in their career who have a
00:04:53.800
baby at home right they're not getting a lot of sleep they're pretty stressed out they use a different text Act in their
00:05:00.120
current role than they have in previous jobs these are all conditions of the
00:05:05.160
body or mind that make it more difficult to do certain activities and I think we want everyone on our teams to feel
00:05:11.680
supported and included and we want to minimize struggle wherever possible and I think that's kind of a key thing here
00:05:17.600
is we're not trying to it's really hard especially as like an individual contributor to
00:05:23.680
like make it to to bring equity in the sense like
00:05:28.800
everyone has the same ability to do their job in the same way right but we're just trying to minimize struggle
00:05:34.680
and so we're g to that's really what we're going to look at in this talk so this is a person who's a
00:05:41.240
software engineer at ABS who over time has been having more and more limited
00:05:46.400
Vision so they started their programming career with full vision and I believe it was a a genetic situation they're now
00:05:52.880
losing vision over time and they said we make our products
00:05:58.080
accessible in some cases but not the processes by which they are built so our development practices
00:06:05.360
themselves are inaccessible so like I said we're going to talk about kind of two main areas here the code itself and then General
00:06:12.280
practices but if there's literally one thing you take away from the talk maybe you have a baby at home right maybe
00:06:18.400
you're not able to like fully engage totally fine if you take one thing away from this
00:06:23.759
talk avoid abbreviations abbreviate when we don't
00:06:29.280
use abbreviations were decreasing the need for context or interpretation we preventing confusion and
00:06:34.680
misunderstanding this is something someone actually said to me in my first week at Red Canary can you bug TSC to
00:06:40.360
connect with the CSM about AWS and CB and now I know what that means and I
00:06:45.960
don't have to think about it but at the time I was just like totally lost felt
00:06:51.360
like an impostor no idea what's going on like let's let's just not do it just don't use abbreviations they really the
00:06:57.960
the benefits do not out the harm all right going into our code let's
00:07:04.479
take a look at how we can improve accessibility in our code through readability naming and linters so first
00:07:12.599
readability we want to have a balance between meaning and length so a lot of things we're going to talk about right
00:07:19.160
it's there's trade-offs so we're looking for kind of where's the happy medium with these things the more verbose it is
00:07:26.080
right the easier it is to understand generally speaking that's not necessarily true again if you have dyslexia or concentration issues um
00:07:34.560
shorter on the other hand right and benefits of of having shorter code is it's easier to skim it's easier to kind
00:07:40.280
of look at as a whole instead of parsing through each individual
00:07:45.440
piece pronounceable words uh this is one I hadn't really thought about until doing this talk um better for screen
00:07:51.759
readers right screen readers are literally reading out your code and so if we're using variable names and Method
00:07:56.840
names that that are words it's much better for screen readers trying to parse that um also makes pairing easier
00:08:04.120
right if you ever been pairing and you're trying to read out a line of code to someone and end up just saying the
00:08:09.240
letters because you can't pronounce it yeah so let's take a look at a couple
00:08:14.680
of examples so this is one that I would argue is a little too short right we have and we're going to be focusing
00:08:19.840
really on the variable names here so we have failed and old like yeah I do like
00:08:25.479
that does have meaning right but it's I can't tell the glance what failed means
00:08:31.440
and what old means here's an example that's maybe a little more information than we need
00:08:37.880
right so has reached Max failures before finishing I do know exactly what that means it's very clear but it's also
00:08:44.399
super long uh next one right has been running longer than acceptable again
00:08:49.640
super super clear but arguably more information than we need and here's kind of one that's like
00:08:56.680
just right so reached Max fails again we can getting the key information here which is that it it's failed more than
00:09:02.720
once and we've hit some kind of Maximum running too long right so old versus running too
00:09:09.040
long gives us a lot more context for kind of what's happening in this code
00:09:15.399
here all right naming we all know naming is the hardest thing right uh the goal here really is let
00:09:21.600
your code be unambiguous and self-documenting we're going to talk about documentation in a
00:09:27.560
bit this is one of like my personal pet peeves is when people use a single
00:09:33.360
letter as a placeholder in a loop reiteration use words just use a word it
00:09:39.560
just it makes it so much easier to follow I was working in a spec file that was like 600 lines long and someone had
00:09:47.959
done a let statement at the very top of the file for subdomain and they said let
00:09:53.480
s and then like Factory bot. create subdomain but I didn't know this I was just trying to change update one test
00:10:00.160
online like 325 and I'm just seeing s everywhere so then I have to go back and figure out where is s being set what is
00:10:07.160
s refer to and if they had just put let subdomain equal subdomain I would have
00:10:13.320
known exactly what I was working with I would have had to do this extra
00:10:18.399
investigation choose existing method approaches that read like sentences I think this is
00:10:23.640
especially uh like there there's special opportunities in in the language like Ruby which is meant to be kind of
00:10:29.839
English right meant to be like we're reading text so really lean into that because that's super helpful for a bunch
00:10:35.680
of people so here's some more examples so this is some code I came across in
00:10:42.040
our uh repository CB equals message. gsub new line
00:10:49.040
blankspace I mean it's it's pretty simple I can tell what's going on here right it's it's okay um but this is
00:10:55.839
better right again we're removing the abbreviation carbon black okay cool and
00:11:01.480
message that gsub new line blank space is is literally doing the same thing like or giving you the same result as
00:11:08.480
message. delete new line but the bottom one is so much easier to read right it's
00:11:14.360
more like a sentence what are we doing we're deleting new lines great let's write
00:11:19.920
that all right linters I love linters I used to be
00:11:25.279
someone who's kind of on the fence spot linters because they can be kind of annoying and a lot of times you'll run
00:11:31.200
into code bases where people are just constantly like disabling and enabling rules to get around them and not
00:11:37.320
actually following the spirit of the lenter um but they really can be a big
00:11:43.279
boost for accessibility so why what makes your code consistent and I would
00:11:48.440
argue more importantly predictable the rules are written down for everyone to reference so if you're
00:11:56.120
you know coming to like Ruby is an example if you're coming to Ruby at a job for the first time and you're not sure what sort of the standards are and
00:12:02.560
the conventions you can just go look it up um it makes it so that there there's
00:12:08.680
no surprises there's no secrets like it's transparent it just makes it makes it a much more Level Playing Field no
00:12:15.720
matter where kind of your familiarity with rubier programming is for example R
00:12:21.320
Canary we use a ton of linters we have rubocop Hamlin esin adelin SC scss and
00:12:28.120
it's great just makes everything it makes it also takes some of the
00:12:33.199
subjectivity out of PR review because we already have the rules that we've all decided on and agreed to follow and it
00:12:40.480
happens automatically so someone doesn't have to come in and say oh hey actually this is kind of hard to read what if you did it this way instead because it's
00:12:47.680
happening in our pipeline before we even get two people looking at the
00:12:53.800
code right some general tips for our code to make it Accessible Line length everyone favorite right
00:13:01.839
um generally speaking we want to be between 75 to 100 characters I think the
00:13:07.240
rubocop default for example for a line length there 100 characters and there are reasons for that um we read best
00:13:16.000
between like I want to say it's like 50 to 75 characters like we literally read
00:13:22.160
best for that New York Times for example their line length doesn't go above 74 characters per line and that's a website
00:13:28.959
that's literally just meant if you're you're intended to consume Big Blocks of text right that's just how we read best
00:13:37.760
um more and shorter lines of code is also better for screen readers generally
00:13:42.880
and when I talk about screen readers one caveat I want to make is that to there are a lot of ways that
00:13:49.279
people can tweak their screen reader setup to their preferences so so screen
00:13:56.360
stuff tends to be very general someone asked after I gave this talk oh well you know I've I've heard that Camel case is
00:14:02.360
way better for screen readers than snake case um and it depends I think it was two it it was two
00:14:10.720
or three of the top four do prefer like do much better with camel case and snake case but one of
00:14:16.720
them doesn't and so it just it unfortunately it's hard to come up with with really hard lines and rules for
00:14:21.880
screen users for some of the more detailed stuff um shorter lines of code is also
00:14:27.680
better for people with dyslexia or concentration disorders right instead of having to like read all the way across
00:14:33.680
the screen and try and remember what was at the beginning you can see it kind of Allin one View and it's easier to
00:14:39.680
process indentation so this is another one right um we were looking for a balance so linters are going to
00:14:46.199
recommend certain things other things are actually better for people you're really just trying to find find something that that kind of rides in the
00:14:53.480
middle um yeah all about balance this was that that was interesting you know we're talking about screen readers and
00:14:59.600
and people are sometimes like well I don't know any programmers who use a screen reader to program right but
00:15:05.480
actually according to Tech overflows programmer survey from 2023 almost one in 50 developers are blind or have
00:15:11.880
Vision issues and this is a spectrum right so like I have a cooworker who is a little older and when I I just know
00:15:18.639
whenever we pair to like magnify my screen a couple times if I'm going to be screen sharing because it just makes it
00:15:24.639
easier for him and I don't know that he would identify as having Vision issues but he prefers when the text is bigger um
00:15:32.800
and again this is a spectrum right that one the the developer Julia who we saw quote from her earlier right people lose
00:15:39.680
visual Acuity over time so some of this isn't necessarily about what do does my
00:15:45.160
team need right now but anticipating like what might future team members need or what might I need in the future and
00:15:50.800
how do we just kind of make it easier for everyone so some more examples so this
00:15:56.720
is fine there's a lot of white space at the beginning and again depending on how you have your screen reader set up some
00:16:02.319
just skip that some don't um this I would argue was a little bit
00:16:07.759
better we've got all of our arguments in a row we've got a smaller
00:16:13.079
indentation you're not having to do as much like back and forth scanning you know if you had a whole form with ones
00:16:19.399
like this where it was The Wider indentation you're doing a lot of kind of moving across like this instead of being able to kind of skim more in a
00:16:25.560
straight line and you might be thinking to yourself like I I get that this could help people but I
00:16:32.040
really hate how it looks like that just bothers bothers me on a deep personal level and I totally get that um but
00:16:40.319
while preference is personal accessibility is global and so the analogy I like to use is imagine if you
00:16:48.279
were in an office and you had to sit in this super hard uncomfortable chair that had like weird spikes on the arms and it
00:16:55.680
was too short for you and there were no wheels and you had to use that every day just
00:17:02.319
because your office manager thought they looked cool right you could do it but it
00:17:07.839
would be it it would be adding unnecessary challenge to your work right
00:17:12.959
just let people pick their own chairs we're gonna talk about that in a little bit too comments this one of my hot takes um
00:17:21.319
I think comments are amazing and broadly underutilized and I know there's that old truism right that like oh good code
00:17:27.679
doesn't need comments um but why not both right clean readable code and
00:17:34.320
helpful contextual comments so what are some situations where comments can be
00:17:39.360
especially helpful let's take a look at a few when you expect to change the code in the near
00:17:45.679
future if it concerns Mission critical functionality like maybe maybe you might think oh well this is so obvious what's
00:17:51.960
happening here but if changing this even a little bit could break a whole bunch of just make that obvious right
00:17:59.440
changing the code could have unintended consequences so I actually had this happen in a PR recently um it was a
00:18:07.200
partial with like we had multiple partials in at different levels with a similar name and I was changing one of
00:18:13.200
them and I was like oh this is only being used in this one email great I'm fine um but it turned out I was actually
00:18:19.120
being used on a random table somewhere else and no one realized it because when we made the
00:18:24.919
change um we also realized that that table itself was super out of date so this is just a page people had been kind
00:18:30.799
of forgotten about um and so now there is a comment in that partial that says
00:18:36.039
hey this is also used here make sure you test both places if you change it and then if the code is particularly
00:18:43.280
complex or complicated right this is often the main area or the main reason why we would put comments in because
00:18:49.600
it's just there's complicated stuff going on and this isn't just for other
00:18:54.679
people right like obviously this is beneficial for early career folks or
00:19:00.039
maybe newer hires who aren't as familiar with the code base but this is also great for you in six months when you
00:19:05.880
have completely forgotten why you made the changes you made right so if if not for anyone else like do it for
00:19:13.159
you and then this is a another key one that we I think we're really good about at R Canary is leaving comments if
00:19:19.440
there's code that relates to an external service or vendor so like hitting an API
00:19:25.159
or relying on a field that's being set you know somewhere else by an external service like that's a great time to
00:19:31.840
leave a comment so here's an example um the comment just says this oneoff is
00:19:39.440
a placeholder to fix an immediate client issue with ragd dolls although I don't know who would have an issue with rag dolls it will be replaced in juror
00:19:46.760
Ticket 1 2 3 4 5 and so this comment acknowledges hey this is kind of an
00:19:52.039
anti-pattern we have a reason for that it's going to be fixed and then they let the person kind of follow the path to
00:19:58.799
see okay where is this going to be fixed how why Etc all right apis I will say I was I
00:20:07.640
was this was a hard talk to put together it was it was more challenging than I
00:20:13.240
expected to find information about how about best practices for accessibility
00:20:18.840
with a lot of this kind of thing so API development we're a little sparse this was the best I could find but if anyone
00:20:25.799
has anything to add or knows more about this like definitely hit me up I would love to expand this section if possible
00:20:31.840
so what are some ways that in our code we can we can make our API development more
00:20:37.280
accessible using consistent descriptive Fields right the best kind of API is
00:20:44.760
when where you're not sure like you know what information you want you're not entirely sure what route is available
00:20:49.960
but you make an educated guess based on other routes and it just works right isn't that just magical it's like the
00:20:55.440
best feeling make your apis like that make them like guess ible um using word separators I thought
00:21:02.000
this one was interesting this is a case where underscores are much better than just
00:21:09.080
like looping it together right so like active underscore file underscore type instead of active file type this is not
00:21:14.640
only again beneficial for screen readers but also people whose primary language isn't the language your API is written
00:21:20.200
in um or who are in a hurry or right just being consistent with that
00:21:27.679
again abbreviation no good don't do it and this I think is an area where it's very easy to do
00:21:34.240
abbreviations so some examples right spell it out so external service instead
00:21:40.400
of X service previous instead of preve preve
00:21:45.600
is one that I see a lot right next in preve I'm like oh they're both four letters that's nice said no just write out
00:21:50.799
previous just do it all right and then if you're using a
00:21:57.440
documentation generator or you know generating your own documentation for your API making sure that your UI is
00:22:04.559
accessible so for example the we use um I knew I was going to forget this
00:22:10.600
because I didn't put in my notes uh whatever the one we use is that we use to oh Swagger we use Swagger to generate
00:22:15.840
our API docs every Canary um and this is what it looks like for full color vision
00:22:22.279
on the docs that are generated and this is an example if you're color blind and you can see that it's a lot harder to
00:22:27.640
see the distin between some of the different um methods
00:22:33.159
right get post Etc so that's another thing to consider is
00:22:38.480
like okay well if you can get the data great but to get the data often you need to read the documentation if you can't read the documentation it's that much
00:22:44.520
harder to get the data and then we're going talk more about documentation in a little bit uh
00:22:51.200
specs and testing how do we make our specs and testing more accessible
00:22:58.840
so high test coverage right serves itself as built-in documentation which makes our code base kind of literally
00:23:04.880
more accessible to people because they have more than one way to kind of dig into it learn more about it get familiar
00:23:11.039
and comfortable with it um test coverage and documentation these
00:23:16.240
are also great for a variety of focus or concentration issues
00:23:21.520
right same rules apply that we've talked about above right use semantic naming avoid abbreviations
00:23:28.840
Etc um I already told my story about my subdomain issue and that massive spec
00:23:34.799
file like just spell it out um and then this is one that I really like to talk about is like
00:23:40.080
writing your test to tell a story because I've had I've had situations where I'm working on a new part of the
00:23:45.440
c-base and the first thing I'll do is I'll go look at the specs and be like okay what's what's currently happening here you know to give me kind of like a
00:23:51.799
overview of the code that I'm about to work in and it's really hard to get that
00:23:57.760
overview if the files are you know like if your tests are in kind of a like a random order if it's like oh we've got a
00:24:04.760
few for Scopes here and then we do some for methods and then we've got some for like an association oh and then here's
00:24:11.200
some more spec one or scope ones like no no no um make your specs tell a story
00:24:17.240
right go in a narrative order so often this is similar to the order that the code is written in in your in the file
00:24:25.200
that you're testing right so if you have scopes at the top in your file put scopes at the top scope tests at the top
00:24:31.159
of your specfile right just kind of follow a similar order be descriptive so
00:24:36.520
I really love using like we use rspec and I I context this under my spec
00:24:42.120
file like context when here some more information that you might need to know then it does this context when hear some
00:24:48.399
more information you might need to know it does this um and and putting a lot of
00:24:53.600
specs in right uh especially if we're talking about like backend tests which be a lot less you know generally right
00:25:00.360
so General tend to be a lot less per you know like have fewer performance issues than if we're doing like UI tests um
00:25:07.360
testing positive and negative assumptions testing edge cases just put it all in there so then when I go like I
00:25:13.120
love when I come to a spec file and it's like okay when this situation is true it
00:25:19.320
returns false if this thing is happened it returns true if this thing has happened it returns false if this thing
00:25:24.760
and this thing have happened it returns you know throws this type of error if you pass in hot garbage like great I
00:25:31.760
just want to see what is everything going on here and it also tells me it makes me more confident that we have
00:25:39.279
thought about all of this before and that if I make changes the tests will catch them if I if I break something um
00:25:46.600
it makes me so much more nervous to to change code with low spec coverage
00:25:52.039
because I might break things that I don't even know exist and we won't find out until it gets to production
00:25:58.679
spell out positive and negative assumptions and then of course you can also write tests to measure accessibility measures in the
00:26:05.720
UI so here's my hot take for code damp tests are the new dry so quick shout out
00:26:12.080
to Amanda Boehner for introducing me to this idea in a blog post this is from that post if our test Suite takes too
00:26:17.919
long for a newcomer to understand it's a strain on velocity if our team members
00:26:23.240
don't feel confident updating it it's a product liability
00:26:29.360
so one example of how do we write damp test damp is descriptive and meaningful phrases versus dry which is don't repeat
00:26:37.480
yourself right so of course as we've been saying this entire presentation it's a balance um one example that I
00:26:45.919
like to think about is I hate when I'm running a test suite and again this is
00:26:51.360
our spec specific but that uses shared examples and so you end up with failures
00:26:58.000
that are like you know this file. RB and then it's like bracket one bracket 3
00:27:05.760
Bracket four comma bracket and it and you have no idea which one actually failed and you have to like do a find to
00:27:12.679
figure out where the actual it I just I hate that it's so it's so annoying um so
00:27:19.600
I personally am not really a fan of shared examples I think there are some there there are exceptions of
00:27:25.919
course one way that I really like that shared examples were used is I had a colleague who wrote a spec file used
00:27:31.919
shared examples but he defined the examples in the spec file and so it was super easy to follow
00:27:38.559
it super easy to debug it didn't end up with like this spaghetti of a spec
00:27:44.559
code so deepen meaningful phrases documentation so we're going to
00:27:49.919
talk about documentation kind of from a higher level here um one thing that I don't have in a slide but that I like to
00:27:56.600
call out is documentation is only as valuable as it is up to date right and
00:28:02.320
it's so easy for us to write documentation for like a new feature we just built and then forget about it for
00:28:07.760
four months so one of the ways that I like to at least for documentation that
00:28:13.080
I've written that I try to mitigate that is I have a repeating calendar event once a month on a Friday at like 2 p PM
00:28:20.559
my time for half an hour and it's just a link to any documentation in our we use
00:28:27.159
Confluence any document ation and Confluence that I have touched and I just kind of quickly skim through and I
00:28:33.000
look and I see like oh have I learned more about this thing since I L touched this or have we changed a process
00:28:38.399
related to this since I L touched it um you know is there are there is there a
00:28:44.559
new documentation we've written that's related that I could like back link to in this older
00:28:52.000
page all right so first there are kind of what I would consider more traditional accessibility concerns right
00:28:57.640
so don't use images of text or code samples or dral outfit right and I think we're
00:29:04.279
all like oh I wouldn't do that but we're in a hurry and maybe we think we'll come back and change it later and we forget to there is nothing more frustrating
00:29:11.600
than being like Oh I need to to collect some client data you know for sales and
00:29:17.120
we've done this before and there's a script and confl I'll just go to the script and Confluence and I'll copy the script but the script is an image and
00:29:24.799
you can't copy it it's the worst go do it just put the actual text and
00:29:31.760
sometimes people are like oh well you know our documentation engine like isn't
00:29:36.960
great about code highlighting cool then put the image and the actual text right give people both
00:29:44.480
options to for how they want to engage with it um making sure your color choices have high enough contrast right
00:29:51.120
and making sure you check in light and dark mode because not not all um like engines are good about doing that the
00:29:57.399
same um and then uh using semantic hierarchal
00:30:04.760
hierarchical HTML right and you can do that whether it's markdown wizzywig
00:30:09.799
straight code um and that last one especially right that doesn't only help with screen readers but also helps to
00:30:16.279
skim and if you have a documentation system that autog generates table of contents right it's pulling from that
00:30:23.120
hierarchical HTML so again these practices help everybody in a variety of way
00:30:30.080
and then including captions or transcripts or video documentation and this is one that
00:30:35.200
like I recognize that there can be barriers to enacting some of these right
00:30:42.120
um one of the things that that we've just kind of kind of started to do every Canary because we have a lot of video
00:30:47.960
presentations is um like older ones where we're not engaging in like live
00:30:53.440
captioning is we play it while having a zoom open
00:30:58.960
and have zoomed do the live transcription and honestly it works pretty well so we've been starting to kind of back transcript some of our
00:31:05.600
video documentation the other thing about this too is you know these these aren't just
00:31:13.279
accessibility concerns in the sense of disability but it also allows people to engage with the content in whatever way
00:31:18.919
is best for them right so some people are visual Learners some people are AO Learners some people really like video
00:31:25.720
you know some people want to read a transcript all listening to a video and so this really gives people multiple
00:31:33.120
ways to learn in whatever way is best for
00:31:38.360
them um oh looks like I turned off my uh automation okay well uh simple writing
00:31:45.159
so simple writing is something I wasn't super familiar with again until I kind of researched for this talk but it's
00:31:51.440
it's kind of what it sounds like people also call it like plain writing or plain language and it's it's
00:31:58.720
being as concise as possible without losing Clarity so one thing I like to bring up
00:32:06.320
with this one is more than one in 10 programmers in stack overflows 2022 survey said they have a concentration or
00:32:12.320
memory disorder that's like more than 10% of programmers have a concentration or memory disorder or if you're on call
00:32:18.720
in the middle of the night we were talking about on call earlier right if you're on call in the middle of the night and something goes wrong your
00:32:23.840
ability to consume large blocks of text is probably diminished and when it's hard to concentrate or to recall
00:32:30.320
information or to process new information you're extra relying on documentation to help you solve problems
00:32:35.360
and answer questions so how do we do simple writing
00:32:40.720
um can move forward that one so avoiding inent this is like a
00:32:46.080
really small thing but honestly most of this talk is really small things right it's not saying overhaul your entire
00:32:52.000
code Bas it's just saying hey next time you add a loop you use a word instead of a letter right um but amp names are
00:32:59.120
apparently like screeners get cranky with those keep your sentences short so we talked about this very similarly with
00:33:05.360
our line link through our code right we said 74 to 100 characters going across
00:33:11.200
but there's a similar concept when we're talking about how long our sentences are so even if it's only 74 characters in a
00:33:17.159
line you still don't want three or four 74 character lines in a row that are all
00:33:22.480
one sentence right so they they did done testing on this they found when the average sentence length is 14 words
00:33:29.600
readers understand more than 90% of what they're reading so they're still missing a little bit but they they understand
00:33:34.919
more than 90% if you go up to 43 words
00:33:40.320
comprehension drops to less than 10% and honestly 14 words is not or it's
00:33:47.600
it's really not that many so making our sentences shorter than we think they need to be really helps with reading
00:33:55.120
comprehension and then you can test the reading level of your text or get AI suggestions for simplifying it right you
00:34:01.639
this is this doesn't have to be like a lot of extra work you can write it the way you normally would plug it into an
00:34:06.880
engine and it'll tell you okay you using too many adverbs or you could swap out this word for one that's simpler um and
00:34:12.760
there's a lot of different ones we can use for that so Hemingway is my personal favorite but it is English only um
00:34:20.240
language tool does up to 30 languages but it does have kind of a pay wall yeah I just saw Jade suggested having yeah
00:34:27.119
it's great um paraphrase tool has more than a 100 languages and there is a free tier I
00:34:33.079
think you're limited on on how many times you can use it or how many sentences you can put in something like that at a time but um but these are
00:34:40.440
great ways to kind of lean into that plain or simple simple
00:34:45.560
language so here's an example from Hemingway so I put in some documentation
00:34:50.960
from Red Canary and it's calling out different ways that I could improve that so four of 13 senten are hard to read
00:34:58.720
and a couple of those are because they have links but as we're going to see I shouldn't have straight URLs in there
00:35:04.119
because they are hard to read um you know it's telling me where I could
00:35:09.320
probably get rid of some passive voice where I have phrases that have simpler Alternatives and so making this kind of
00:35:16.520
a step in your documentation writing process helps make sure that it's accessible for a wider variety of
00:35:24.640
people some additional tips and tricks documentation so like I just said link
00:35:29.839
text um link text should be informative not click here or we're going to see an example of that in a second um write
00:35:36.920
your dates and times in unambiguous ways so I gave this talk at htic Ruby in Zurich
00:35:43.680
and people I think a lot of people there are on teams with with Americans and
00:35:49.440
just laughed really hard when I did this part uh May 10th right is it 510 or is it
00:35:55.599
105 it just depends where you're from but if you have to guess that's bad
00:36:01.240
because someone's gonna guess wrong and then avoid using socially charge terms for technical Concepts and
00:36:07.319
you might think well what does that have to do with accessibility you know again if we're if we're trying to minimize struggle if we're trying to create
00:36:13.480
environments where everyone can Thrive and be successful that's really hard for some folks to do if we're using terms like
00:36:20.240
these and so I'm going to give a couple of examples um these are American English examples but I think some of
00:36:25.480
them because a lot of Tech is in English kind of permeate wider than that um but
00:36:31.560
I'm sure wherever you're located you can think of ones that would apply for for your your context and culture so allow
00:36:38.319
list versus white list right we want to be using allow list main instead of
00:36:44.560
Master Core feature instead of native feature and again these are all pretty
00:36:50.720
small things but we all know that small things add up into big things over
00:36:56.119
time so here's an example so the top one is okay right click here to learn more
00:37:03.280
about changes to Native features coming 612 2025 but there's ambiguity here
00:37:09.160
where am I going when I click here if I click on click here where is it going to take me is it taking me to more Internal
00:37:14.480
Documentation is it taking me to the code is it taking me to external documentation like where am I going with
00:37:19.640
that um again 612 is that December 6th
00:37:25.160
or is that June 12th kind of makes a kind of makes a big difference if we're talking about new
00:37:30.720
features coming and then we have the better example right you can learn more about the changes to core features
00:37:36.000
coming June 12th 2025 in the vendor documentation so when I click on this
00:37:41.920
link I instantly know okay I'm going to the vendor documentation perfect
00:37:47.200
removing ambiguity and then there's some about kind of overall communication so being
00:37:54.160
careful of assuming cultural context watching for G assumptions or
00:37:59.720
exclusion please everyone if you haven't add your pronouns and name pronunciation to your profile in slack or teams or
00:38:07.160
whatever you use um and then also make sure you're checking other people's so I have a
00:38:15.119
coworker and his name is spelled x i
00:38:20.560
AO and I had been pronouncing it Shia because that's that's what I remembered him telling me when we first met like
00:38:26.960
Shia okay great but I kept hearing people in meetings saying xia so I thought oh have I been saying it
00:38:33.319
wrong this whole time and like I didn't want to ask him because I'm sure he gets asked a lot so I went to his slck
00:38:38.359
profile and he had his pronunciation there and it turns out I was right it was shout so everybody else was making
00:38:45.720
an assumption maybe they knew someone who pronounced it that way maybe they misheard it the first time but it'd be
00:38:51.640
so easy to clear up by just checking his profile and seeing how he pronounced it
00:38:57.200
so so if you haven't added yours please do and then avoiding phrases like it
00:39:02.720
should be easy right because what's easy to you is not easy
00:39:08.760
to somebody else for a whole variety of reasons right some disability related right if you have a concentration
00:39:14.599
disorder things that are hard for you might be easier for someone else and things that are easier for you might be hard for somebody else if you're a newer
00:39:20.760
programmer if you like all of these are reasons right there's so many reasons why your easy is not somebody else is
00:39:27.680
easy so I like to say things like you know I think it's pretty
00:39:34.560
straightforward but hit me up if you run into any issues or I don't know how long
00:39:40.280
it's going to take but I think you're just going to need these two files and it should be all contained in there right or if I remember it correctly we
00:39:47.359
have good test coverage for this but let me know if you hit a snag so trying to be more specific about why we think it
00:39:56.200
will be less challenging and like telling them resources for it but also assuming that it will be hard
00:40:02.920
and opening that that path for someone to then come back and be like oh hey actually I looked at that file and we
00:40:08.280
have really shitty T like tests haven't updated in two years so I'm going to need some more guidance
00:40:14.160
cool all right and then real quick we're going to talk about General engineering policies um these are Beyond obvious
00:40:21.079
ones like gender neutral paid family leave or having a wheelchair accessible
00:40:26.280
building right and we're going to focus specifically on policies that that tend to to relate to engineering
00:40:32.400
organizations so how do we Empower people to work effectively flexible work schedules this is a huge one right I
00:40:38.839
think after the pandemic we're all aware of of how much this can benefit folks choosing vendors and tools that
00:40:44.560
prioritize accessibility so you could have the most accessible code base at your company but if you're vendor for
00:40:50.920
documentation and for support tickets and you know for for um whatever have
00:40:57.040
you like if all of your external or your your like HR software for payment right
00:41:02.359
if all of that isn't accessible you don't have an accessible working environment
00:41:07.400
right um providing Education and Training on how to support colleagues with disabilities because the owners should not be on them to teach others
00:41:15.920
right we should just be educating ourselves um and then offering folks a variety of tools to get the job done so
00:41:22.160
this is one that I hadn't really thought about until I was researching this talk but there's a great quote I want to share tools like K9s can make using
00:41:28.960
kubernetes more accessible for individuals with dyslexia or color blindness than using Cube cuttle
00:41:35.280
allowing developers to customize their setup to their preferences is a crucial aspect of enhancing
00:41:41.520
accessibility and so again there's always trade-offs right because a trade-off here might be oh well if everyone's using the same code editor
00:41:49.040
then it's easier to debug issues or when we're pairing we're all familiar with the setup and that's all true
00:41:56.040
but I would argue that whenever possible it's better to let people pick
00:42:02.400
according to their preferences than to enforce strict guidelines but what people have to
00:42:09.560
use um all right so wrap up uh most of the work for accessibility right on the
00:42:15.720
back end comes from small individual efforts we're not talking about some
00:42:20.800
huge overhaul we're just trying to be more deliberate about the code that we write the documentation we write the
00:42:26.280
apis and specs right changes to make products or processes easier to use
00:42:31.720
benefit everyone and this is the big one even if you rarely touch the UI like I know in
00:42:38.000
my current role I'm hardly ever doing things in the in the front end you can still have a big impact on accessibility
00:42:44.240
for your colleagues and your co-workers and then avoid abbreviations
00:42:51.640
please uh one of the four core values at R Canary is to be kind and authentic and I think that applies here right striving
00:42:58.040
for accessible working environments is just the right thing to do for our colleagues so thank you I have a bunch
00:43:06.160
ofs and then I've got my email and also we're hiring so if you're looking for a job red canary.com job openings I'm
00:43:13.599
happy to chat with anyone about what it's like to work there
