Bug reports are probably the most hated bits of literature in the lives of software developers, but they’ll always hold a special place in my heart. Writing bug reports gave me my first taste of technical writing, and in fact led me to technical communication as a field. It also gave me my first taste of the kinds of problems that afflict technical communication as an occupation.
Bug reports offer interesting insight into the world of technical communication as a whole. For as short and simple as they are, bug reports have all the elements of good technical writing and suffer from most of the same adversities. Namely, most bug reports are bad because technical writers aren’t the ones writing them.
By nature, bug reports need to be simultaneously concise and descriptive. If you’re overly wordy, explaining every opinion you have on the software and every detail that led to the bug, down to what you were wearing and what the weather was like, no one’s going to read more than one of your reports. On the other hand, if you submit “This function is not working as intended, please fix,” I can guarantee that some developer somewhere is plotting how best to kill you. Writing a good bug report requires someone who can distill information sent in by angry users and over-tired testers and compile it into something clear, concise, and useful to be sent to hassled and harried developers. In short, it requires tech writers, and unfortunately that’s not who’s writing them.
A large part of the blame for this lies in the fact that most people don’t understand why such a specialized vocation is needed. Who would know how to explain something to developers better than other developers, right? Why would you spend money hiring a whole other person to come in and write these reports? While this mindset is certainly troubling, what I find equally worrisome, if not more so, is the over-reliance on technology to do the heavy lifting.
With the advent of cheap and powerful bug tracking software, it seems hard to justify paying someone to write bug reports. The important element that’s often being missed, however, is that these programs are excellent organizational tools made to help technical writers, not replace them. Zendesk and JIRA are wonderful, but they just can’t do the work of even a single technical communicator.
Pictured above: An excellent organizational tool
Not pictured above: A technical writer
The problem arises when people believe these programs can do more than they’re actually capable of and assume they’ll do most of the work in making bug reports usable and useful, leaving the actual writing of the reports in the hands of developers who are unqualified to write good reports and busy enough with their own work anyway.
The biggest shame if this, in my eyes, is the misuse of what would otherwise be an incredibly powerful tool. Good bug tracking software, in the hands of a skilled technical writer, can allow for tracking trends in software issues, assigning bug fixes quickly and evenly across developers, and responding immediately to users’ problems. It can allow a single person to keep things running smoothly amongst developers, asset providers, and stakeholders. None of this will work, however, without the one thing that bug reporting, and in fact much of the technical communication field, is missing: a competent tech writer to tie it all together.
-Evan Taylor
Technical Communication at UAHuntsville 