For most companies, maintaining documentation is a manual task that feels more like a chore than a joy. It’s entirely decoupled from the software development process, there’s never enough time to get it done, and docs are quickly outdated. Worse, in situations where unfinished work gets pushed into the future, there’s the added anxiety of technical debt.
Despite the fact that developers overwhelmingly benefit from well-written, updated docs, the tasks of writing and updating documentation are repeatedly pushed to the back burner.
Swimm has an answer to each of these problems: Continuous Documentation.
Benefits of Continuous Documentation
Continuous Documentation is a paradigm for documentation pioneered by Swimm for creating, maintaining, and finding existing code documentation as part of the regular development workflow.
Documentation with Swimm’s Continuous Documentation Platform is code-coupled, always up to date, created when best, covers what’s important, and consumed when needed.
Continuous Documentation has several cascading benefits, like improving developer onboarding, creating a culture of communication and knowledge sharing, and treating documentation as a first-class citizen for dev teams. When code and docs are intertwined, and on equal footing, teams are more productive.
Getting started with Continuous Documentation is straightforward, but the first foot forward depends on where your team culture stands with documentation.
- Is it a regular practice?
- Or is it something that’s been mostly or entirely avoided?
In either case, our team at Swimm has realistic approaches that are proven to lead to successful and sustainable documentation.
How to integrate Continuous Documentation into your workflow
The most important thing to remember about integrating Continuous Documentation into your workflow is that it really depends on your starting point vis-a-vis documentation.
Most companies are in one of two situations when it comes to documentation:
- Situation 1: There’s basically no documentation, or at least nothing useful or reliable
- Situation 2: There is some documentation, but it’s rarely in sync with the code
Each situation requires a different set of actions in to establish a successful Continuous Documentation capability. Some challenges are cultural or mindset-related, some are process-related, and others are technological.
When you have no docs, start with a “docuthon”
There can be a dozen reasons why there are no docs, and we know it’s a common problem, especially for startups with small teams where knowledge is shared but not written down in any way.
When companies grow, and documentation hasn’t taken precedence, we highly recommend docuthons. It’s exactly what you think it is: a hackathon for documentation.
When we have a new customer who’s essentially starting from scratch, docuthons are an ideal launching point to gain momentum and get people onboard with how easy and quick it is to write and maintain documentation with Swimm. Integrating Continuous Documentation into your workflow is, on some level, undoing the ideas that are usually the starting point for most developers: that documentation is hard, pointless, not worth the time, etc.
#1 Some of the basics of a docuthon
- Set aside around 2 hours for your devs to focus on doc creation.
- Every dev should be assigned a specific code area – preferably an area they are well familiar with.
- Keep things simple; your first docs need to be helpful, not comprehensive.
- Look for the low-hanging fruit: repo or file structure, guidelines and best practices, etc.
#2 Identify essential parts of the code in your docuthons
Before writing a single word of documentation, be sure to go through the codebase and identify five to ten of the most essential aspects of the code. They can be flows, snippets, classes, business logic, or anything else notable in the code.
The point is to identify what a new person would need to know about that codebase, whether they were just hired or came from another team after a couple of years.
#3 Start writing once you have topics
Once you’ve identified key aspects of the code, you need to figure out what to write that will be most useful for anyone onboarding to a codebase. This is when titles become : “How to…” or “Why we…” or “What is….”
Docuthon writing participants can come up with titles, or they can be requested by other repository stakeholders. Start writing once you have 10, and you’re ready to put together a Documentation Playlist.
When you already have some docs
Most teams that have started with docs understand their value but can’t always keep them up to date with rapidly-changing code. Docuthons are an excellent approach for these situations, but there might be enough documents in place to build a Documentation Playlist. The bigger concern is ensuring the current, most essential docs are relevant and updated.
#1 Start with tickets and assign docs to the individuals who best know that part of the code
Some teams with existing documentation may already have a backlog of documentation or at least a backlog of technical debt. The issue for these teams is less about discipline and more about prioritization. With Swimm, you can assign documentation to teammates, allotting them time to complete the work.
#2 Ensure documentation meets best practices
When there’s existing documentation, Swimm can help teams stay organized with tags and Playlists. It’s good to establish some best practices for tagging and taxonomy early on in the push. Successful teams will likely also have a sense of the type of documentation they’re writing, like whether a doc is a “how-to” or something else.
#3 Consider who will consume the docs in the future and how
- Will there be something that we learn in this sprint that is worthwhile sharing with other team members?
- Is the information about this task public knowledge, or is it worthwhile to echo it beyond the team’s boundaries?
- Will any knowledge essential to future contributors be lost if we don’t document it?
How to enforce Continuous Documentation in your workflow
Swimm’s strongest value is the ease of creating docs coupled with the enforcement of consistent, up-to-date, relevant documentation. It is the strongest asset in integrating Continuous Documentation into your workflow.
At Swimm, we have four strategies for enforcement:
- Make sure docs are up to date across the whole codebase
- Only alert or block a PR if it’s a doc that a dev broke while iterating specific code
- A mix of both
- Including documentation in the Definition of Done
Doc strategy option 1: ensure docs are always updated across the codebase
When considering this option, there are a few hurdles to manage and potentially overcome. It is the most strict form of enforcement, meaning it has the potential to be the most frustrating for teams early on in their Continuous Documentation journey.
Option 1 is challenging because, ultimately, it doesn’t matter if specific devs work on code affecting docs they didn’t write. Swimm will still flag the change and block the pull request until the documentation is fixed.
- On the upside, strict enforcement is the most obvious way to keep docs alive and relevant.
- On the downside, developers may be annoyed that they can’t merge their code because the docs are out of sync.
It’s worth noting that this option can also be set to be non-blocking and just warn users. But it may be easy to fall into old habits and ignore the warnings as they come in.
Doc strategy option 2: hold devs personally accountable for their code changes
Developers are usually great with personal responsibility. If they introduce a breaking change, they will fix it. Hopefully, the CI/CD pipeline will block the breaking code from deployment, but even if it doesn’t, devs have to rebase and roll back capabilities.
Swimm understands this unspoken practice and brings it to the documentation space. For these reasons, we recommend Option 2 as a good long-term enforcement option.
If a dev tries to merge a documentation-breaking change, Swimm will notify the developer about which documents are affected and how. The dev will know and understand that their actions caused this issue, and Swimm gives them the opportunity to remediate it.
Doc strategy option 3: best of both worlds
In the short term, we recommend a blend of the two options for companies trying to get to the point of meaningful Continuous Documentation.
In this option, not all doc-breaking PRs are blocked, and developers are notified that their changes are doc-breaking. The notifications can be raised to managers with high-level oversight and work prioritization responsibilities.
Doc strategy option 4: include documentation in the Definition of Done
At Swimm, we include the creation of new documentation in the Definition of Done (DoD) during our sprints. Documentation becomes a part of the process of developing new features.
Bottom line
When you integrate Continuous Documentation into your workflow, the most important thing to do is to make sure the most critical areas of the code base are documented. Once that’s done, use that to onboard new hires and see how it works. Iterate and improve from there. It’s already a huge win to be at this point.
Once all devs are on board, they’ll add more content and keep it updated. We’ve found that adding documentation to your workflow is an organic process when using Swimm. You don’t have to do much work because Swimm does all the hard accountability work for you. Everything else we’ve found will follow suit: enforcement, freshness, and consuming docs when they’re most needed. The benefits are inevitable, and docs become a communal effort.
Getting started with Continuous Documentation is easy—and free. Sign up for a demo and see Swimm in action up close
