Why most technical documentation fails (and how to fix it with inclusive, accessible design)
By: Thor K. Salehi
For many people, technical documentation is the first point of contact with software, an API, or a complex system. They are often the only guide a user will ever consult. However, these documents frequently carry implicit expectations of prior knowledge, familiarity with domain jargon, or a certain level of technical fluency. Primarily, this approach arises from pressure to deliver compact, efficient content tailored to seasoned professionals who simply want the facts post-haste.
Balancing clarity, accessibility, and efficiency is genuinely challenging, and this is exactly where problems arise. Something intended as a helpful gateway quickly becomes an insurmountable barrier for most. Beginners frequently feel overwhelmed. Neurodivergent readers struggle with unclear structures and dense formatting. Users with disabilities encounter inaccessible content. Additionally, language differences, varied learning styles, and limited access to formal education or regular exposure to sufficiently advanced technology compound these barriers even further.
As someone deeply engaged in software development, communication and teaching, I am passionate about creating resources that empower and guide everyone. Armed with a blend of knowledge from engineering, psychology, neurophysiology, and learning theories, along with about a decade of practical experiences, my aim is establishing a framework for writing documentation that is of use to anyone. Doing this will not only benefit underrepresented readers but significantly enhances the reader experience for everyone.
Next, we will investigate a set of principles we can use to overcome some common pitfalls and finally we will create a framework of best practices that can be deployed in action.
Principles of Inclusive Technical Documentation
The human brain thrives on predictable patterns. When information follows clear, consistent patterns, neural pathways strengthen, facilitating easier recollection and durable understanding. But it suffers from issues of information overload and parallel processing when dealing with sufficiently complex data.
Technical documentation in turn, is often unplanned and hastily constructed, causing it to run into a lot of these limitations through densely packed paragraphs, unclear instructions, unclear hierarchy, incoherent technical jargon and poorly formatted text. These problems are then further complicated by individual learning preferences and neurodivergence which is commonly estimated to affect about a fifth of the adult population.
To find a good path forward, we turn to cognitive sciences with the explicit aim to enhance coherence, recollection, and precision, resulting in the following set of principles for technical writing:
Clarity: Simplify content using clear language and relatable examples to reduce cognitive load and help readers easily grasp new concepts.
Consistency: Maintain uniform terminology, phrasing, and formatting to create predictable patterns that reassure and reinforce learning.
Modularity: Divide content into focused, manageable sections, each addressing specific goals to help readers navigate information comfortably and confidently.
Progressive Disclosure: Present information gradually, building complexity only after foundational concepts are understood, thereby enhancing motivation and retention.
Accessible Design: Employ clear typography, appropriate spacing, visual aids, and interactive elements to accommodate diverse learning styles and abilities, ensuring inclusivity and ease of understanding.
Embedding these principles into your documentation practices will result in technical resources that support a diverse audience, improving learning outcomes, usability, and satisfaction for all readers.
If you are interested in the science behind these principles, you can read the more comprehensive version here.
Writing and Design Best Practices
Principles are great on paper, but they are useless if they can’t be used in practice. So let us now construct a set of applicable practices to apply when writing complex technical documentation:
Enhance Skimability
Use short, descriptive headings and subheadings to guide readers. If a paragraph gets longer than half an A4 page, using normal font and line breaks, consider if there is a natural way to break it into shorter segments.
Poor: A lengthy block of text describing installation steps.
Better: Short, numbered steps clearly outlining each action required.
Improve Readability
Employ simple sentences and active voice. Use clearly define words and avoid technical jargon. If abbreviations, domain specific names or jargon is needed consider including a vocabulary section and always define the word clearly the first time the abbreviation is used. Remember that if you have to use abbreviations in your illustrations, the readability rules still apply.
Poor: “The DB init sequence should subsequently be commenced.”
Better: “Step 2: Initialise the DB (Database) using the “src/scripts/db_init.sh.”
Facilitate Navigation
Include a detailed table of contents with clearly defined segments. Each segment should have a distinct purpose and an identity. Use consistent link styles and intuitive navigation elements and when referring to other concepts within the same document, consider linking back, via hyperlinks where possible but otherwise by paragraph header.
Poor: As stated by www.cooldb.com/models/imprt/fastScript.html you can you import the model with the model import tool.
Better: As stated by CoolDB — Fast Script Documentation you can you import the model with the model import tool (see Database — Data Import).
Support Diverse Learning Styles
Complement text with illustrative visual resources. Clear diagrams, screenshots, and videos can be used to reinforce key point in a way that is accessible for those experiencing reading or concentration difficulties. They also help as a high-level introduction to the concept that requires a low time investment from the reader.
Poor: The data Ingestor gets messages from the API Gateway. The data is passed to the Data Cleaner module for processing and storage. When the database has stored the data, a response is sent to the cleaner that responds back to the API Gateway. Each ingestion is also registered in the Statistics Engine for analytics.
Better:
Providing an image as the centerpiece, accompanied by a comprehensive caption or short paragraph describing the image.
Ensure Visual Accessibility
Images on their own aren’t good enough if they don’t follow good accessibility hygiene guidelines. Choose high-contrast colour schemes and readable fonts. Shapes and colour are also not just aesthetic choices, but a language that can be used to tell a story. Remember that for readers with visual or image processing impairment, providing a descriptive alternative text and a clear caption is paramount.
Poor: Images without alt-text, adequate description, and with a low-contrast colour schemes.
Better: Images with concise, descriptive caption and alt-text using high-contrast colours for readability. You can mouse over the image below to see the alt text.
Tools
Following the above example-driven practices will significantly improve the inclusivity, clarity, and effectiveness of your technical documentation. But it isn’t always easy. So, to help you, here are the set of tools that I use when writing documentation and preparing presentations to make this a little easier for you. Importantly I am not sponsored by and not endorse these tools as the ultimate solution to your problems and my personal toolkit is always evolving. These happen to be the tools I currently use.
Colour Palette Generator
For those without visual impairments or a background in visual arts and design, understanding how colours interact can be challenging. Colour visualisation and palette tools can help you create cohesive schemes based on your chosen colours, providing various styles to match your preferences along with examples for you to see and choose from.
Venngage — Accessible Colour Palette Generator
Accessible Palette — Palette Generator with Contrast and Brightness
Generative AI
A useful application of LLMs (Large Language Models) and generative AI is their ability to provide human-like feedback on text. For example, you can submit a document and ask the AI to evaluate word choice, sentence structure, paragraph length, and more. However, public AI tools may store your input for training, so avoid sharing confidential information or content protected by intellectual property rights. A good rule of thumb is: If you’d be happy posting it on LinkedIn, it’s safe to share with the AI.
Markdown
Personally, I prefer the clarity and flexibility of Markdown over traditional tools like Microsoft Word, Google Slides, or LibreOffice. Not only does it offer easy version control through your preferred source code management platform, but it is also customisable via themes by your readers and has a wide range of export options to formats like PDF and HTML, which are ideal for sharing documents, a topic we will return to when discussing automation.
typora.io — Browser Based Markdown Editor
Diagrams
Creating consistent, accessible, and version-controlled diagrams can be challenging with many tools, as they often prioritise visual polish over structural clarity. Tools like Mermaid and draw.io address this by supporting clear, visually accessible diagrams that complement written explanations. Mermaid enables diagramming through code, while draw.io allows manual drag and drop creation. Both offer advanced theming, flexible layouts, and version control, making them well suited for producing comprehensive and inclusive visuals.
Mermaid — Diagramming and Charting Tool for Markdown
Draw.IO — Diagram and Flowchart Tool
Conclusion
I hope that you can, by applying these science-based strategies and principles, transform the technical resources at your disposal and to turn them from mere manuals into welcoming, intuitive guides. My goal and my hope are that through thoughtful and well-structured communication, we can create environments where everyone feels capable, confident, and truly empowered and foster a culture that promotes knowledge, sparking curiosity, and nurtures continuous growth.
Bio: Thor K. Salehi
I am a a full-stack software engineer, hobby behavioural scientist, lecturer, and Gen AI expert working as a Solution’s Architect at Volvo Group Connected Solutions. I love tackling everyday problems with novel solutions, agile thinking, and a dash of chaos. I design, build, teach, read, complain and apparently don’t sleep.
I have written a previous article on Medium:
AI in the service of software developers
