Guiding to Safety: How Technical Documentation Writers Can Encourage Software Security

Forty years ago, a publisher halted sales of a cookbook because of a custard recipe in it. The problem? The recipe reportedly would have created a small explosion (but no custard). Other past mistakes in recipes would have led to bland, burnt, or even toxic dishes.¹ Recipes can be sensitive to mild tweaks, so cooks often follow them closely. If a recipe omits an ingredient or skips a step, no sign of a problem may appear until the first bite.

In software development, a seemingly small mistake can also have a serious but subtle security impact. For example, TLS is a protocol that facilitates secure communication online. Errors in its use can open the door to attacks like eavesdropping. A 2013 study explored the sources of TLS errors in mobile apps.² The study revealed that some developers had unwittingly copied insecure example code found online. The code appeared to work, masking serious issues.

Software developers use a variety of tools when building software. Formal documentation for those tools is a key source of guidance. While developers are responsible for the security of their own software, documentation can help steer them to safety. A single piece of documentation may influence numerous developers, whose software in turn affects countless consumers.

This piece aims to assist writers of formal developer documentation, such as a detailed programming language reference or tutorials on programming for a platform. The Federal Trade Commission has more than twenty years of experience in protecting consumer privacy and security. For this piece, we consulted with experts on documentation for developers. Based on those discussions, we suggest ways that documentation writers can guide software developers toward more secure practices.

Developers and documentation

When creating software, developers use building blocks like programming languages, development platforms, frameworks, and libraries. Formal documentation for these tools is an important source of guidance for developers of all skill levels. This piece is for writers of that documentation.

If documentation addresses possible security hazards, it can aid developers in creating safer software. It can also teach valuable lessons. Suppose that a developer would not think to guard against excessive failed login attempts. Documentation can address the threat and teach the developer to think of the threat on future projects.

In trying to promote security, documentation writers face many challenges. Those challenges range from limited resources to unpredictable developers. For example, a developer may arrive at a random page of online documentation from a web search. That developer may jump to the instructions to complete a narrow task—at the extreme, just copying example code—missing guidance and warnings from nearby text.

In spite of these challenges, writers have learned ways to encourage stronger security practices by developers. Based on consultation with documentation experts, this piece presents some of those lessons. This is not a comprehensive, rigid checklist, and preferred practices may evolve. As a result, these points should merely complement the expertise of documentation writers.

Documentation is not a panacea for security risks, and documentation alone is not always the best way to lead developers to safe choices. Still, documentation can play a positive role in promoting security. The ten tips below may help documentation writers in their important work.

1. Write documentation with security in mind

When writing documentation, keep security in mind. Doing so may help you to anticipate and address security-relevant details. It can also help you to make security guidance a coherent part of the documentation.

Tangentially, those designing programming languages, libraries, etc. may wish to keep documentation (and security) in mind when building those tools. Think about how to explain both the tool and security factors while designing and building it. This may yield a higher quality tool and result in better documentation for it.

2. Make security guidance hard to miss

Offer security guidance in ways that would be hard for developers to miss:

• Raise relevant security details in context. If certain parameter choices for a function could create security risks, explain the parameter and risks in documentation for the function.
• Use fonts, colors, and other cues to emphasize important security points.
• If example code may pose risks under some circumstances, insert comments directly in the code that explain the issues. This may reduce the odds that the risks go unnoticed should a developer carelessly copy and reuse that code.
• State any assumptions relevant to security. Use the previous tips to draw attention to those assumptions.

Where security details may be overwhelming (such as a beginner tutorial), creative options and further research may help ease this tension. For example, some websites have blocks of text that users can expand and collapse. A “collapsed” security explanation that readers can expand may be worth testing.

Do not assume that developers will read your documentation from start to finish, including all explanations and warnings. Try to ensure that they learn what they need to know from the limited text that they read. This does not mean that separate sections focused on security are a bad thing. For example, a final pre-release security checklist might be a great additional resource. Encourage developers to review such resources, but avoid assuming that all will do so.

3. Make examples secure

Insecure examples can cause real vulnerabilities. Suppose that example code uses an outdated, unsafe algorithm. Developers who simply copy and paste that code could create vulnerabilities in their own code. Some developers may ignore even clear warnings surrounding the example code. As a result, your examples should be as safe as possible under common use cases. Be sure to highlight any remaining risks and assumptions prominently.

4. Write correct documentation and keep it correct

Incorrect or outdated documentation can cause mistakes. It also may drive developers elsewhere. Beyond careful editing, be sure to:

• Address any errors quickly.
• Keep documentation up to date with changes in the documented tool. Highlight changes in the tool that may have security implications.
• Test example code to ensure that it works as expected after changes to that code or updates to the documented tool. Automated testing of example code may help.
• Clearly specify the version of the documented tool that documentation covers.
• Add a last-updated date to help developers infer when documentation might be out of date.
• If appropriate, remove older versions of documentation to prevent confusion over the latest guidance. If not, add hard-to-miss warnings to the older documentation, and refer readers to the latest guidance.
• Give a way for readers to report any errors they find. Developers also may uncover security issues in the documented tool itself. Learn the process for notifying that tool’s developers of security issues, and share that process with readers too.

5. Use feedback and available data to refine documentation

Even the best documentation has room for improvement. To ensure that documentation addresses developers’ security needs:

• Provide an easy-to-find channel for developers to give feedback and report errors.
• Browse developer forums and watch mailing lists for common questions, mistakes, misconceptions, and concerns. Use these to refine your documentation.
• If feasible, test draft documentation with developers. Guidance that is clear to you may not be clear to readers. Tests with drafts may expose ways to make your guidance more effective.
• If you have analytics data, use it to understand how developers reach and use the documentation. This may suggest ways to improve the documentation.

6. Help developers identify problems

Code that seems to work can hide serious security issues. These issues could put consumers at risk. For example, a piece of software can appear to work even if it uses insecure cryptography. Developers may benefit from advice on how to spot such issues. Your documentation can suggest tests or other ways of detecting problems. Details and examples—including test code—can help developers to catch and fix problems.

7. Share technical preferences that can improve security

Share your security expertise, especially technical preferences that can bolster security:

• If you believe that some options provided by the documented tool are safer than others are, say so. For example, maybe you think that certain function or parameter choices are better from a security perspective. If so, tell developers your preferences and the reasons for them.
• Mention other trusted tools that can provide security benefits. Suppose that a third-party library for a web platform helps protect websites against brute-force login attempts. Reference that library in documentation for the platform. This may help developers find a critical tool.

In general, try to explain the reasons for your security-driven suggestions. A developer who understands these reasons is less likely to make mistakes that undermine security.

8. Encourage broader security-beneficial practices

Share related practices that can help developers improve the security of their software. For example:

• Stress the need to keep the documented tool and its dependencies up to date. When possible, explain how to do so and how to learn of updates. If the documented tool has a way to inform developers about security patches or other important issues, tell developers how to subscribe.
• Discuss and offer examples of how to create automated tests. This may increase the odds that developers write such tests. In general, raise good software engineering practices.
• Help developers prepare for security issues in their own software. For example, suggest setting up a system for users to report these issues, like a monitored email address.

9. Customize documentation to use cases

A tool may have multiple common use cases. Different use cases may come with different security concerns. When writing documentation for a tool, consider providing customized guidance for each of the tool’s common use cases. Think broadly about developers’ needs in each case. For example, a developer trying to encrypt data might also need help with generating and storing encryption keys.

To avoid confusion, be sure to highlight the relevant use case for particular customized guidance.

10. Apply existing documentation-writing lessons

If developers find documentation hard to use, they may make mistakes that harm security, or they may turn to less trustworthy resources. Documentation writing is a specialized skill. Strong documentation may hide the many thoughtful choices by its writers.

Look for examples of good documentation with similar topics, readers, or goals. Seek out applicable documentation guides, standards, and templates as well. Use these when appropriate, and consider the lessons in these materials. Take advantage of advice from the larger community of documentation writers too. Preferred practices for documentation evolve, so even experienced writers may learn new lessons from time to time.

Return the favor too. Perhaps you will have opportunities to impart lessons learned. If so, share methods that have proven successful for you in driving better security practices. Regardless, your thoughtful documentation alone can be a positive example for others.

Complements to documentation

Documentation is far from the only way to encourage strong security practices by developers. The best strategy may include tactics beyond documentation, such as:

• Secure defaults: Like good documentation, good tools account for developer experiences and needs. Suppose that a programming language makes a task easy to complete, but developers must take other steps to address a security threat. Developers may not check documentation if they are unaware of the threat or do not realize that other steps are needed to address it. Features that default to safe behavior under common circumstances may reduce this risk. Such features can be flexible in case a developer requires different behavior.
• API cues: APIs often contain subtle guidance for developers via the cues they include or omit. A developer might expect a function named doTaskX to perform task X. A developer familiar with doTaskX may not know of a separate doTaskXSecurely function. A safer option may be to name the secure function doTaskX and the insecure one something like doTaskXInsecurely. API developers should consider the cues they convey through choices like names. Emphasize clarity where confusion could create risks.
• Support via IDEs: Many developers create software in integrated development environments (IDEs), which bundle tools used in the development process. IDEs sometimes contain features that help developers make decisions and catch errors. These features could offer tailored security guidance to developers, and they could warn of potential security issues.³
• Usable security for developers: An easy-to-use tool can help you do your job well. The same may be true for developers using tools to build secure software. An emerging field explores the impact of usability factors on the security of software that developers create.⁴ Future research in this field may provide new lessons and ideas.
• Software development practices: Good software development practices can help developers avoid and catch security issues. They may also help educate developers. Advances in these practices—and tools supporting them—may allow more secure software with less effort.

• Informal resources: Documentation is not the only place that developers can find help. A developer might find the answer to a thorny question in an old blog post or on a developer forum. Those who create or maintain informal resources should consider how to promote good security practices.

This list is not comprehensive. Experts generally recommend a layered approach to security: use multiple safeguards so that the failure of one is not fatal. Strong documentation is simply one safeguard for helping developers create safer software.

More information

For companies seeking practical security guidance, Start with Security: A Guide for Business distills lessons from more than fifty FTC law enforcement actions into ten actionable tips. Stick with Security: A Business Blog Series takes a deeper dive, including some preferred practices. In addition, the FTC Business Center's Data Security portal features a wide range of guidance and resources.

Footnotes

¹ For more on recipe errors ranging from the unappetizing to the hazardous, see:

• M. Burros. "Cookbook Follies: Recipes That Fail." The New York Times. September 17, 1997.
• F. Cloake. "Cookbook Errors: Recipes for Disaster." The Guardian. September 19, 2011.

² S. Fahl, M. Harbach, H. Perl, M. Koetter, M. Smith. "Rethinking SSL Development in an Appified World." 2013 ACM Conference on Computer and Communications Security (CCS 2013).

³ D. C. Nguyen, D. Wermke, Y. Acar, M. Backes, C. Weir, S. Fahl. "A Stitch in Time: Supporting Android Developers in Writing Secure Code." 2017 ACM Conference on Computer and Communications Security (CCS 2017).

⁴ Y. Acar, S. Fahl, M. L. Mazurek. "You Are Not Your Developer, Either: A Research Agenda for Usable Security and Privacy Research Beyond End Users." 2016 IEEE Cybersecurity Development Conference (SecDev 2016).

May 2019