Invalid bug reports are sometimes documentation bugs
Most open source maintainers know the pain of dealing with invalid bugs. These are bugs that are already listed as known issues, that are intended behaviors, that aren’t reproducible, unsupported versions, or any number of other explanations. They waste time on the maintainer side in the triage, investigation, and response. And they waste submitter time, too. Everyone loses. While it’s frustrating to deal with invalid bug reports, almost no one files them on purpose.
Researchers (including Muhammad Laiq et al) have investigated invalid bug reports. One of the recommendations is to improve system documentation. This makes perfect sense. When there’s a difference between the expected and actual behavior of software, that’s a software bug. When there’s a difference between the user-expected behavior and the developer-expected behavior, that’s a documentation bug.
There will always be some people who don’t read the documentation. But those who do will file better bugs if your documentation is accurate, easy to find, and understandable. As you notice patterns in invalid bug reports, look for places to improve your documentation. Just like the dirt trails through a grassy area can tell you where the sidewalks should have been, the invalid bugs can show you where your documentation needs to get better. (Note that this applies to process documentation as well as software documentation.
As with all interactions in your project, a little bit of grace goes a long way. It’s frustrating to deal with invalid bug reports, but keep in mind that the person who filed it is trying to help make your project better. And often their bug report represents a real bug — just not the one they think.
This post’s featured photo by Neringa Hünnefeld on Unsplash.