How to Track and Document Known Issues Effectively in Software Projects
Selecting The Best Approach To Collect And Document Frequent Issues For Improved Troubleshooting
One of the most valuable habits I’ve observed among experienced developers is creating notes. Instead of repeatedly solving the same problem or reverse-engineering a past issue, they consult personal documentation first. It’s something that I also picked up, and now my notes are full of simple “how-to” guides or solutions to issues I encountered.
Since then, multiple times, someone reached out to me to ask about their problem, and I had a ready-to-use solution. If this happens more than once, my note gets promoted to software documentation.
The problem with the error messages is that they rarely give you precise answers to how to resolve it. Usually, the solution is to search for answers online. The bigger the organization, the more restrictions there are, which cause issues very unique to a given project. You might do everything according to instructions, yet it won’t work because of network restrictions, the custom package used by the project, or a script that only your company uses.
Documenting all the issues does not scale with the growing codebase and team because it becomes impossible to gather all the issues. It will also become difficult to search for the solution you need.
Every team I worked with had different ways of documenting errors and their explanations. None of them is the ultimate solution suitable for every project because it depends on the team.
Messaging Platform
A messaging platform is the most common way of sharing solutions to the issues developers encounter. Usually, it’s tools like Slack or Teams that contain all the solutions to the most common issues. It is natural for developers to ask for help and share error messages, and they usually receive an answer.
This approach does not need content maintenance and encourages collaboration if the encountered issue has not yet been solved. That makes it very convenient. Yet, it has lots of disadvantages.
Searching the archive of issues might not be that difficult if some rules are followed. It’s possible if you have a dedicated channel for that, and it becomes extremely difficult if the developers discuss encountered problems on private, closed channels.
The messaging platform is rarely used as documentation, so I have never seen anyone add tags to speed up searching for information. This makes it harder to find, especially if the issue is poorly described.
Even if you find the answer you were looking for, you don’t know if it’s the proper solution. It might be outdated or misleading. It’s because it's not maintained or moderated. Messaging platforms lack the possibility to upvote the issue, mark the accepted solution, or any incentives to respond to issues.
Known Issues
In a research conducted in 2018, only 2.36% of JavaScript packages included a “Known Issues” section in their Readme.1
In my opinion, it’s a really bad result, given how useful that section can be. Gathering the most common problems significantly speeds up the onboarding.
While it adds the responsibility for maintaining that section, developers can be more certain they use the accepted solution.
The biggest issue is a lack of search. Markdown files stored in repository are difficult to discover and explore if not rendered as a web page.
Stack Overflow Business
Stack overflow business is another interesting solution for handling known issues. It’s more suitable for bigger teams, and it’s a paid tool.
It has all the great things - the ability to discuss the issues, accepted answers, and downvotes. The ability to gather points and badges incentivizes developers to contribute. This gamification aspect relieves the maintenance burden. Developers usually improve answers themselves.
It’s also a very familiar tool for developers because it has the same layout as the original Stack Overflow.
Stack Overflow Business allows you to create communities, so it’s easier to explore technologies that you are interested in. For each community, the most active users become subject matter experts, making finding support on your issue easier.
When it comes to search, it’s not great. Original Stack Overflow usually gets traffic from search engines instead of using their built-in search. While it’s not great, search can be used successfully if developers focus on adding tags to questions.
Summary
Gathering the most common issues is important in a growing team. The most challenging part can be deciding on a solution because they all come with some drawbacks. For me, the hybrid approach works well. Discussing the issues on a dedicated Slack channel and a markdown file with the most common issues can fulfill that function well.
How Mentoring Can Inspire You to Become an Impactful Leader
Becoming a mentor for the first time changed a lot for me and set the course for my entire career.
Mastering Codebase Scaling: A Guide for Large Developer Teams
The first encounter with a project for a software engineer is usually a university assignment or personal project to start learning programming. It often starts with one person and one great idea for an app. It feels like you can achieve anything at this stage. You can build something useful just by pulling a one-nighter. You don’t need to focus on qual…
S. Ikeda, A. Ihara, R. G. Kula, and K. Matsumoto, "An Empirical Study of README contents for JavaScript Packages" IEICE Transactions on Information and Systems, vol. E102-D, no. 2, pp. 280-288, Feb. 2019. Available: IEICE Digital Library.