Documentation is a user security issue

Jess Schalz
7 min readSep 25, 2024

--

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.

A vector graphic of multiple computer screens in primary colors, showing documents
Image by blossomstar on Freepik

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.

A vector graphic of two people communicating over text, with a tablet between them frowning
Image designed by Freepik

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):

Two tweets from @buri_tech on twitter. Tweet #1: [We have the same issue. We have several cases where in the response from your API “status” field is NULL. We have recipient IDs if you’re interested. (endpoint /api/1.0/messages/send.json)] Tweet #2: [I found out what’s wrong! When email sending is soft-bounced or hard-bounced then “status” field is null! This is not documented in API documentation. Is it a bug or a feature? :)]

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:

A code snippet from Stripe’s payments/quickstart documentation. The security warning reads: “This is a public sample test API key. Don’t submit any personally identifiable information in requests made with this key. Sign in to see your own test API key embedded in code samples.”

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”.

A meme of an early 2000s browser homepage heavily infected with spyware
You’ll never find the right link again.

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.)

An email from the author to the Medium team, asking if the github.com/Medium/medium-api-docs repo was still maintained.

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.

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.

--

--

Jess Schalz

Software engineer turned technical writer and autistic as heck. (she/they)