Documentation is a user security issue
On the intersection of software development, security, design, and how documentation impacts all of them through user behavior.
Documentation is required for software. Without written proof of the software’s features, users don’t engage with it. Without recorded history of development, work is duplicated, deleted, or contradicted.
There’s more, though. What if documentation can also passively teach our users better information security habits? What if documentation can create positive (and negative) expectations for our users regarding a product’s behavior? What if documentation can prime our users to be phished?
Let’s talk software, security, and design, and where documentation intersects.
Documentation, user impact, and you
Documentation occupies a unique position: it is often the first place a user forms an impression of a product. The quality of documentation greatly influences a user’s perception of the product (and a company in general.)
There are some easy ways to improve quality: code snippets, project templates, effective search functions, easily readable pages, etc. These methods are frequently discussed regarding the usability of a knowledge base. I’d like to discuss some usability aspects that dive further into the implicit behavior of users.
UI (in)consistency
Let me start this section by being very clear that I’m not trying to insult designers. The work y’all do is necessary and difficult, and frequently out of your control. I love working with designers and I have no interest in folks targeting them with bad takes.
That being said, inconsistent design systems negatively impact a product.
From a documentation perspective, UI elements are often included in guides and tutorials to show users exactly what to expect from the frontend. If these elements are out-of-date or inaccurate to the frontend the user experiences, the dissonance breaks the user’s trust and the documentation is no longer deemed reliable.
The natural follow-up thought to an incorrect screenshot is to wonder what else in the docs is incorrect. Once the veracity of the docs is questioned, the user may not find the docs worth using.
Inaccurate screenshots are just one way UI inconsistency can manifest in documentation. Other ways include: descriptions of buttons, menus, and symbols; broken links/navigation; and unexpected frontend behavior. Johannes B. Ullrich, Ph.D posted a great example about how poorly designed UI in security tools can actually be harmful.
Adam DuVander included this screenshot in Examples of Bad Documentation (and How to Do Better):
When a user’s trust is broken, the inconsistent UI elements train the user to expect and accept any behavior from the product. With no expectations for behavior and presentation for the product, users are required to become more risk-accepting of whatever occurs in the frontend.
This primes users to accept anything presented to them from the product, including potentially malicious pop-ups, warnings, or emails. In this way, inconsistent UI trains users to practice poor security habits.
Passive security awareness
All documentation should include examples of how to use a feature. Examples reduce the cognitive load placed on a user when implementing the feature in their own workflow. Not all examples are actually safe for users, though. Many demonstrate only the most basic way a feature functions, and exclude security headers, options, or warnings.
Ensuring examples have security warnings in the code snippet itself reduces the chance a user ignores precautions.
Here’s an example from Stripe, where the code snippet includes a warning to not send PII with the given key:
Security training and awareness don’t inherently solve risky behavior. There’s conflicting data on whether or not technical training and awareness reduce susceptibility to phishing. However, following the defense-in-depth security philosophy, building security into sample code encourages users to consider it themselves, and provides one more potential layer of defense.
By adding security information into examples, writers train users to behave more defensively, and that behavior reduces the workload of security and support teams.
The Federal Trade Commission’s Bureau of Consumer Protection put out a great resource for including security in documentation, and I referenced it heavily when writing this article.
Undiscoverability
When using a feature, access to information about the feature is critical. Finding relevant answers to their questions promotes a user’s sense of autonomy. This experience is also called “discoverability”. From the Interaction Design Foundation,
Discoverability refers to how easily users can find features, information, or functionalities within a product, service, or system.
If documentation isn’t discoverable, users won’t read it. Any security advisories, warnings, and best practices are therefore ignored. Lack of access to information frequently leads to workarounds, inappropriate use of a product, or the dreaded “shadow IT”.
These unexpected uses can not only hurt the customer with unintended data loss or unreliable feature functions, but it also hurts the teams maintaining the product. Support teams have to dedicate time to answering very niche questions, security has to verify data integrity despite features not directly supporting it, and product teams have messy metrics to detangle.
Product stability and security is directly impacted by how easily documentation is found. The more discoverable the docs, the more likely the user behaves safely.
Determining discoverability of knowledge across a company is difficult. UXPin created a blog article about ways to evaluate discoverability; CHAOSS has a very helpful list of survey questions and quantitative metrics; and Tom Johnson wrote an incredible article about discoverability and its (complicated) relation to learning for his blog “I’d Rather Be Writing”.
Multiple sources of truth
Developers generally like to know their work is reliable. In order to verify their work is well-tested and ready for the public, code is (hopefully) run through multiple test suites before deployment. When something fails, a granular error message helps the developer understand where the bug lies.
Sometimes the bug isn’t the fault of the developer at all, but the fault of a product they use. When a product updates and doesn’t alert its users, diagnosing test failures become frustrating and time consuming. To support developers, changelogs and release notes are critical.
I wrote about this happening in another article: Medium REST API Example Calls with Python Requests. I had to email Medium to ask if their public API repo was still maintained. (Spoiler alert: It wasn’t and there was no changelog to tell me that.)
Changelogs and release notes can serve another purpose: acting as a source of truth for unexpected product behavior. Documenting updates not only helps users work smoothly. It also allows users to double check their experience against what the product should do. If a user wants to diagnose or verify a feature’s behavior, access to multiple consistent sources of truth builds trust. Building navigation to all the sources of documentation about a product creates more ways a user gains confidence in their work.
Not all documentation requires in-depth updates for small feature changes. Tutorials aren’t appropriate for internal API changes, but changelogs and release notes are. Additionally, if the feature is open source, the user can see the actual development history for the feature. Transparency in development and feature behavior is powerful when working with technical users.
Multiple sources of truth also act as a preventative measure if malicious actors gain access to a product. If a user encounters unexpected behavior, they can check the documentation, changelog, or release notes for more information. If they find no information about the unexpected behavior, they can reach out to a support or security team with their concerns.
Information transparency provides a shared expectation with the user: what they see is what they’ll get, and anything else should be questioned.
Documentation is obviously necessary for software’s success, but the consequences of design, examples, and availability reach far beyond usability. Documentation affects the literal reputation of a product and company. It affects the safety and behavior of users. It affects the workloads of supporting teams. It affects everyone and everything that touches the product.
The key takeaway from this blog post, if you skimmed: take time to consider how your written content looks to an outsider. Does it hurt (or help) your users? Does it hurt (or help) your product? Does it hurt (or help) your reputation?
I’d like to argue for using documentation as a form of social engineering, much like how designers use design systems in UX: encourage users to behave in desired ways without them noticing. I’m not a psychologist or a designer, but we can borrow from these principles to effectively interface with our users so they enjoy using our content — without feeling overburdened by alerts, updates, and notices.
This article covers some of the more subtle impacts of visual and sustained perception of documentation and how it relates to a product. Practical advice and strategy for leveraging content will be covered in an upcoming article.
Sources
The following are resources I learned from but weren’t cited in this article.
- How to get the most out of software documentation by Sharon Gaudin @ GitLab
- Secure Software Development: Best Practices, Frameworks, and Resources by Hyperproof
- What is the SSDLC (Secure Software Development Life Cycle)? by HackerOne
- User Awareness about Information Systems Usability. Studies in Informatics and Control by Suduc Ana-Maria, Mihai Bîzoi, and f g Filip
- Navigating Trust: The Impact of UI Usability on Perceived Security by Christoffer Billman
- Bad UX Design Always Leads to Compromised Security by Jacqueline Carter
- Affective Design of E-Commerce User Interfaces: How to Maximise Perceived Trustworthiness by Florian Egger
About the author
Jess Schalz (she/they) is a software engineer-turned-technical writer. She has a terrible cat named Sudo, and the two of them live in Minneapolis, MN.