Google Cloud’s 2021 Accelerate State of DevOps report demonstrates that teams that move fast using good practices and tools produce better software, and are less likely to break things. What’s particularly notable about the 2021 report is that they added a documentation section for the first time. GitHub’s 2021 State of the Octoverse makes similar claims:
Building on top of others’ work in a community-like way can be an accelerator, both in open source and in companies. Documentation often signals if a repository is reliable to reuse code from, or if it’s an active project to contribute to.
Yet, despite documentation’s admitted importance, the stereotypical developer remains notoriously bad at documenting their code. The documentation that exists is often rife with outdated assertions, inconsistencies, or is altogether absent. Because maintaining good documentation is so painful, and its rewards appear dubious at best to many practitioners, rethinking the entire process is a boon to the industry.
We recently talked with Swimm, and were very interested in their approach to code documentation. Swimm is a recent entrant into the code documentation space and is offering a refreshing (because automated) alternative to the notoriously tedious task of manually authoring software docs. I found their pitch particularly compelling based on my past experiences as a developer and teacher of technical communication. Needless to say I know these pain points well. Swimm justifies the merits of maintaining excellent documentation in terms of lessening the friction from onboarding, knowledge silos, and context switching, but it was the potential improvements to developer experience that particularly caught my eye.
According to Omer Rosenbaum, CTO and co-founder of Swimm, the answer to DevX’s documentation woes is Continuous Documentation, which ensures the Documentation is 1) Always up-to-date, 2) Created when best, and 3) Code-coupled. In his manifesto for Continuous Documentation Rosenbaum argues that the importance of automating this process is tied to “building and updating documentation incrementally, thereby keeping it in sync with the codebase.”
Swimm promises to improve the developer experience by automating this process. By pairing with VS Code, among other IDEs, as well as GitHub and CI integrations this technology auto-syncs documentation. In response to the subjectivity which plagues documentation, they also offer templates to suggest best practices and areas that are probably in need of documentation. Whether Swimm has created a new product category with its continuous documentation platform is yet to be seen, but I, for one, am interested in the space it opens up.
Disclosure: GitHub, Google Cloud, and Microsoft (VS Code) are RedMonk clients. Swimm is not currently a RedMonk client.
No Comments