Technical Writing: Accessible Writing for Developers
Bekah Hawrot Weigel
Our primary goal as technical writers is to be understood. It’s not to sound smart, be elite, be gatekeepers of knowledge. It’s to convey information to our readers in a way that’s effective for understanding. Beyond that primary goal, there are other benefits. Using strategies to make your writing accessible makes you more likely to retain your audience, have a broader audience, and have readers return to your content. We’ve talked about some of the concepts in the post in Technical Writing: A Beginner’s Guide, but in this post about accessible writing, we’ll take a deeper look at understanding our audience, our word choice, and even go into sentence structure.
Audience
As developers, we’re frequently writing for a general audience. Many of our readers aren’t going to be native English speakers, may be neurodiverse, or may be beginners in the field. Below are some ways to make technical writing accessible to a general audience.
Word Choice
Jargon: Words often specific to a field that wouldn’t be understood by a general audience or those new to the field.
One example of tech jargon is “rubber ducking.” What does that mean? Well, it’s a shortened phrase for “rubber duck debugging” that comes from The Pragmatic Programmer by Andrew Hunt and David Thomas. Debugging means exploring why there’s a “bug” or problem preventing the code from running as expected. As a concept, rubber ducking means explaining aloud your code line by line to help you to identify the problem and find a solution. Developers sometimes have a toy rubber duck to talk to as they work through a coding problem.
Photo by S. Tsuchiya on Unsplash
Acronyms: Words formed from the beginning letters of a group of words. For example, UX/UI is an acronym for User Experience/User Interface, which could also be considered jargon. User Experience Design focuses on identifying and solving user problems. User Interface Design focuses on creating an intuitive design that a user will interact with.
Numeronym: A numeronym is a word that contains a number either to represent a sound (k9 means canine) or to represent a number of letters that have been replaced to abbreviate a word. Most commonly, we see A11y represent the word Accessibility in tech. The eleven omitted letters between the ‘A’ and ‘y’ are represented by 11.
Organization
The organization plays a significant role in creating technical writing that your readers can more easily understand. Think about it this way: if each of your ideas or concepts are a puzzle piece and they’re all mixed up, it doesn’t make sense or form a beautiful picture. But once those pieces are put together, you can see the image and how each piece completes the puzzle. In the same way, each of our paragraphs is a piece of the puzzle that should help form a complete picture. They should hold a particular spot in your writing that helps to support the overall main idea.
Structure
Breaking down your writing into paragraphs with headings and subheadings is another way to make your writing accessible. A long paragraph can deter your reader, especially if they have focus issues or visual impairments. Having a clear structure can also help ensure you have a well-organized piece of writing. Your headings can act as a type of outline for your technical writing.
Give Clear Directions
If you want your reader to perform an action, clearly tell them what you want them to do. For example, if you’re telling them to copy code and add it to an existing file in a repository, where do you want them to put that code? Should they copy the entire code block? Are they replacing any of the existing code?
Link Text
If you have link text, is it meaningful? Does it say “Read More” or “Read more about Accessible Writing”? There should be a way to differentiate your links on the page. You can use the title of the page or the subject to provide specificity.
Assessing your Writing
Creating accessible content can be hard when you’re not used to it. Here are some tips to help determine if your writing is accessible:
Scan your document to see if there’s a clear sense of purpose and main ideas. This can help you determine if your section headings are clear and if your paragraphs are well organized.
Give your draft to a reader in your target audience. Are they able to understand and comprehend your writing?
Define terms that aren’t recognizable to your audience.
Proofread your writing or use a tool that helps to check grammar, sentence structure, and clarity.
Resources
The World Wide Web Consortium (WC3) provides tips and instruction for how to write accessibly
ASE Simplified Technical English works to make “technical texts easy to understand by all readers.”
Amy Dickens's talk “Improve Your Writing Using Accessible Language” for You Got This shares the importance of using accessible language and strategies and tips to do that.
Jargon File: A site dedicated to hacker jargon.
Making technical writing accessible helps remove barriers to entry for learning new concepts and creates a more inclusive space for everyone. This post is an introduction to accessible writing for the web. If you want to know more about accessible writing, please check out the resources above, and hit us up with any questions or suggestions on our @deepgramDevs Twitter account.
If you have any feedback about this post, or anything else around Deepgram, we'd love to hear from you. Please let us know in our GitHub discussions .
