Documenting a piece of software is hard work, regardless of who uses it. We have to think about describing the features and functionality of the software, documenting any potential limitation or security issue, and keeping it all readable for everyone. Thankfully, lots of great tools exist to make this process easier for developers and writers alike. But what about tracking the status of your documentation? How do you know when your documentation is outdated or needs to be updated?
This problem is one I have personally experienced on multiple occasions, and I have seen many attempts at solving it through processes. I have seen organizations use a required step in their agile process to force developers to write documentation or contact the documentation team. For each well-organized documentation process, there is also one where individual developers have to take care of documenting everything. Even with the best system in place, there often is a disconnect between writing documentation and a team's development process. Documentation is rarely, in my experience, a core part of the development process in the way tests are. I have heard the sentence "we can't invest in documentation, it gets outdated too quickly" far too often.
Features or bug fixes require a developer to write the code, write tests, ensure the quality of the code, get a PR review, deploy it...the list goes on. Especially in smaller teams, it falls on the developer to write the documentation for that feature or fix it into that list. It's a lot, and it's hard to track for managers and team leads. If the tools to write documentation do exist, the offering is not as great when it comes to documentation tracking or productivity tools.
Long introduction short, documentation is HARD. For developers commonly tasked with writing user documentation and other developers alike, tracking the work and surfacing it to the whole company becomes very important.
I created Savoir to resolve some of those issues.
Tracking your documentation status from your code
When I founded Savoir, I knew my problem statement but I had yet to find the right solution. Even selling that solution was a far-off dream. After many prototypes and a lot of research (including validating multiple solutions with a researcher in Human-Computer Interaction), I proudly present to you our first product.
Savoir is a GitHub application that acts as both a chatbot and a GitHub check on your pull requests. When a developer pushes some code to a repository with Savoir installed, our bot (nicknamed savoirbot) reads which files were changed (but not the code itself, we never download your code) and compares that against the previous documentation status of your code. If a file has been changed or updated, Savoir tells you in that pull request and gives you the tools to update your documentation. This is all done through comments, if you tag Savoir in an issue or pull request, you can give it commands and it will update your documentation for you. Consider it a like member of your team working diligently in the background to keep an eye on outdated documentation and prompting you to update when needed.
I believe that code is the best source of truth for the status of the documentation of a piece of software. Documentation describes features, limitations, security issues, and usage. Code is the building block of that software. If it changes, it is very likely to be changing the software itself, and thus your documentation might get outdated. Tracking the documentation status through code allows you to act on this early. Savoir basically takes the grunt work out of this process so you can focus on building your code.
Another GitHub check?
One of our core values at Savoir is "integrated". A tool like ours should integrate directly into our users' existing workflow, and not disrupt it. Let's face it, most developers live in GitHub (or your git provider of choice) and that's where most of the magic happens. An integrated tool shouldn't ask developers to open a new tab or window, everything should happen right alongside pull requests and commits.
I explored many possible solutions as I have been building Savoir, from a completely separate product to a browser extension. What finally made me settle for a GitHub application/chatbot was the experience of using Dependabot. When Dependabot is enabled on your repository, the bot will create new pull requests to update any dependencies of a project. While it is now directly integrated directly into GitHub, the experience of triggering actions from a bot without ever leaving GitHub screamed "integrated". Savoir expands on that pattern to provide a documentation tracking tool that is truly integrated into GitHub.
GitHub checks may seem annoying on the surface, and they definitely can be. It's a challenge we are very aware of and guides how we think of Savoir as a product. We will be tweaking and improving Savoir as we go to make it as useful, integrated, and seamless as possible. I hope to see you join us on this journey.
I'd love to hear your thoughts - please comment, share and follow.
We are building up Savoir, so keep an eye out for features and updates on our website at savoir.dev. If you'd like to subscribe for updates or beta testing, send me a message at info@savoir.dev!
Savoir is the french word for Knowledge, pronounced sɑvwɑɹ.
