How to document agile software (without losing your mind)
On how to integrate documentation in your software development lifecycle as a process, rather than an afterthought.
This article is the companion article to “Documentation is a user security issue”. Both can be read as standalone pieces.
Documentation in process today
The state of documentation in software development is incredibly varied. Ask one hundred technical writers how they work with their teams, and you’ll get one hundred different answers.
Best practices frequently focus on the knowledge base itself. I personally haven’t come across many strategies in technical writing regarding documentation integrated in cross-functional teams. Advice on how to more effectively work with your subject matter experts seems to be hidden away in exclusive mentor-mentee relationships or Slack threads. (Shoutout to the Write the Docs Slack community!)
Not only is this frustrating, but it harms our users. Poor process means poor documentation. Poor documentation means poor user experience.
I’d like to draw from broader software development frameworks to suggest some best practices writers can use as inspiration. The following strategies borrow from Dev(Sec)Ops, agile development methodologies, information security best practices, and egoless team structures. They may not be a good fit for you or your organization. I encourage everyone to read this article as a suggestion, rather than a rule.
Incorporate writing sooner
Agile SDLCs (software development life cycles) are generally accepted as the “modern” approach to writing software. Where documentation belongs in this lifecycle, however, depends on who you talk to.
According to sdlcsforms.com, documentation is written in the “Deployment” and “Maintenance” phases of a traditional SDLC. GeeksforGeeks includes product documentation in the product testing and integration phase.
Other agile practitioners believe documentation should be written throughout the entire lifecycle, starting when defining requirements and continuing through development and maintenance. Some practitioners even lean towards “documentation-driven development” (or “spec-driven development”) as a way to use written specification as a blueprint.
On top of that, secure software development lifecycles (SSDLCs) include documentation in all stages. The internal documentation necessary to build software in SSDLCs can be multi-purpose, as they can also provide context and frameworks for external documents. DevSecOpsDocs breaks down some ways documentation can be multi-purpose on their Best Practices page.
To repurpose documentation from others teams, writers must build relationships with them. Ask your security teams what information they require regarding features and products released to the public. Ask your management teams what design documents or specifications they need before they creates project timelines. Ask your support teams if you can view their backlogs and identify documentation priorities. These resources act as source material for later product documentation.
The goal of incorporating documentation throughout a development lifecycle is to reduce friction when writing later. Anyone who works in software knows that without constant vigilance, documentation falls behind and users bear the brunt of misinformation. Security teams know this pain intimately and consequently created the phrase “shift left”. When security “shifts left”, every member of a project builds security into their development process. As writers, we can borrow this process. We can “shift left” our documentation efforts, too.
Where documentation fits in your development process is individual to you. Not every team has the resources to build documentation immediately and forever. Some teams always sprint and have to create docs as they go. The purpose of this section is to consider where you can use information already in the SDLC to your advantage, rather than treating documentation as a separate entity.
Security through obfuscation
We’ve all been there. When deadlines loom and a feature isn’t fully developed, it’s easy to say, “Send it. We’ll fix it later.” When a technical writer speaks up about needing documentation for the unfinished feature, it’s also easy to say, “We’ll wait to write documentation until the feature is finished. We don’t want to advertise it because it isn’t done.”
Sometimes that’s the right move. Sometimes your immediate business needs outweigh process. Sometimes you have to push patches and hotfixes before your client loses all their customer data. I get it.
The underdeveloped feature is a disaster waiting to happen.
As timelines move and more deadlines loom, the feature either becomes waylaid tech debt, or the worst case scenario happens: users start adopting it. The feature isn’t secure by default, its behavior isn’t reliable, and there’s no written proof of it actually existing.
Assume users will find your work. Security through obfuscation fails in this scenario, and excluding immature features in your documentation isn’t viable. Rather than ignoring the feature, document it.
How do we un-obscure features? We start by doing inventory. Work with engineers to determine which features aren’t documented properly. Here are some approaches:
- Create a list of features by product according to your user-facing documentation. Is this list complete and up to date?
- Review API code per product. Are all the user-facing endpoints documented?
- Prune your backlogs. Which backlog tickets were abandoned? Revisit them and decide if they’re still relevant.
- Prune your branches. On git platforms, like GitHub and GitLab, branches typically represent in-progress work for features. Investigate whether branches in your code base reflect your current knowledge base.
When we discover underdeveloped features, and we decide it needs documentation, we face another problem: how do we document it? GitLab has a great guide on indicating experimental/beta features and AWS’s Cloudscape has great guidelines on visually representing in-progress work. As discussed in this article by statsig, clear communication is critical when a feature under construction.
I said that this article has suggestions, not rules, but honestly I’d take this strategy as a rule. Security through obfuscation doesn’t work, your users act in unexpected ways, and transparency about your features is healthier for everyone.
Cross-functional teamwork
Technical writers don’t exist in a vacuum. Here are some ways documentation and other business functions directly support each other.
Security
- Clearly written security expectations reduce support tickets. (I discuss this in the “Documentation as a security issue”.)
- Defining feature documentation can expose security vulnerabilities.
- Ask what compliance information you need to know about the product. As the final reviewers of product documentation before it’s released to the public, you may notice something’s wrong when investigating feature behavior.
Design
- Collaborating with design teams can streamline documentation updates with screenshots of product interfaces and user interactions.
- Designers can provide valuable feedback on the frontend of the knowledge base and help create more cohesive experiences between documentation and product UX.
- We can learn from each other. Designers have specialized knowledge of design programs. They can create diagrams with design software to enhance our documentation (or teach us how to create those diagrams ourselves!)
- Designers create the face of the product. Visual and written perception operate together to create a user’s overall impression of a product’s trustworthiness and competency.
- Ask about accessibility guidelines before publishing content. Designers frequently work with guidelines like Section 508 (in the US) and can provide feedback on written content regarding user accessibility.
Quality assurance (QA)
- Collaborating with QA ensures accurate and verified code snippets and examples.
- QA can catch errors in documentation drafts by cross-referencing with their test results. (This also gets engineering’s attention. When QA catches an error, engineers want to know why.)
- QA uses test environments and (hopefully) automated testing. Technical writers can borrow from their resources to ask questions and learn more about the work without disrupting engineering time. (Engineering time isn’t sacred. We can and should interrupt them. Unfortunately, engineers are frequently on fire and can’t spare time for complicated questions.)
- When engineers provide documentation examples, sensitive info must be purged from it. QA can consult on what info is sensitive, and provide safe example info instead.
Support
- By comparing support tickets and written content, writers can define topics users struggle with most.
- Creating knowledge bases for technical documentation and non-technical documentation better segments intended user experiences. Different audiences require different information. Support can provide the foundation for which audiences to target.
- Support teams are the front line responders for a product. Every support representative is closer to the customers than sales or management will ever be. If technical writers want candid user experiences and feedback, we must talk to support. (Every support rep in this world deserves a raise.)
The original title for this article was “Integrating Documentation in Software Development”. While I think that title is true, I also think it’s incomplete. In researching, I kept coming back to the idea that nothing I wrote down was new. Professionals have been practicing these strategies above for decades. The frameworks I cited come from professionals across the industry in engineering and information security.
By applying these frameworks and strategies to technical writing, my hope is that we can reduce the friction and stress of documentation and instead treat it like another technical process. We can refine, adapt, and iterate. We can integrate ourselves and help others without blocking progress. In order to grow with the industry, we have to step outside our comfort zones and ask ourselves how we can work better with our coworkers. What do they need from us? Better yet, what do they want from us?
Once again, I’ll repeat that these are suggestions. I’d love if people took these strategies as inspiration and shared their own successes (or failures) with me based on their experiences.
Sources
The following are resources I learned from but weren’t cited in this article.
- Secure Software Development: Best Practices, Frameworks, and Ideas by Hyperproof
- What is the SSDLC (Secure Software Development Life Cycle)? by HackerOne
- What is Specification-Driven API Development? by Nordic APIs
- Documentation Driven Development by Blacklane Engineering
- Documentation-driven Development by John Samuel
- On Documentation-Driven Development by Steve Richert @ Collective Idea
- 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.