Ain’t No Bugs On Me

Way back in 1947 Rear Admiral Grace “Amazing Grace” Hopper documented for the first time in programming, a bug. More specifically, it was a moth that had decided to party between two solenoid contacts which shorted out an electro-mechanical relay at the Harvard Computation Lab. Amazing Grace, also known as “Grandma COBOL” didn’t have Trello, Asana, or Jira back then, so she documented the bug on a piece of graphing paper:

A lot has changed since Amazing Grace’s day, and bugs–of the digital variety–are far more common due to the fact that software is exponentially more complex and touches every aspect of our daily lives. Bugs are viewed differently from developer to project manager to product owner to end-user and being mindful of those different viewpoints is critical to stopping any bug infestation. If you find that bugs, like the ants on your kitchen counter, are a bit too abundant for comfort, here are five ways you can manage:

1. Have a requirements document

A requirements document, also known as a functional specification, is critical to the success of any project. In their own headspace, product owners and stakeholders usually have a crystal clear vision of their product. But that vision can lack practical details about how the app should work in the real world.  When the development team makes a good-faith effort to bring that vision to life, the product owner may be confronted with details that don’t fit the way that they think the app should work and that is frustrating from their perspective.

It is the job of a business analyst and/or the project manager to tease out of the stakeholder a complete map of their vision–including aspects that they may not have considered–and to document that vision in the form of a detailed functional specification that tells the developers exactly how the app should operate.

This may seem obvious, but in our hyper-agile world this step of creating a blueprint for the project is skipped more often than you might think and too frequently the developers get blamed for not using their own “common sense” because there was a disconnect between their vision and that of the product owner.

2. Know the difference between enhancements and bugs

It is very difficult for stakeholders to articulate the optimal way in which an app should behave when they are working with their imagination alone. Often, it takes iterations of development, then feedback, then further development before a final release. This is perfectly normal–the stakeholders need to see the app, experience it, play with it a bit, before they can say, “this registration path is a bit more cumbersome than I intended”. The problem in this scenario is that sometimes a project manager will take such feedback from the stakeholder and label it as a “bug” when in fact it is an enhancement.

As a rule of thumb, if the issue being documented isn’t breaking the app and the end-user can still complete the user journey (e.g. successfully register, successfully add a product to their cart, etc), then the issue is not a bug, it is an enhancement and should be labeled as such.

Some developers interpret the term “bug” as “you made a mistake here” and rightfully so: developers are often the only party blamed when things go wrong even though they are only one part of the software development team. With this in mind, you can see how being told that they made a mistake because they didn’t anticipate how a stakeholder’s vision would evolve over time can be a bit irritating. 

As a PM or stakeholder, the best way to alleviate this situation when documenting new issues is to substitute (in your head) the term “bug” with “mistake”. In fact, before you log it, think of the developer who will get the ticket and say to yourself, “Johnny, you made a mistake because _________.”. If the sentence sounds preposterous in your head, then it will sound preposterous to your developers as well–label it an “enhancement”. On the other hand, if the sentence is not ridiculous (“Johnny, you made a mistake because you didn’t add a logout button when it was clearly in the functional spec and wireframes. Now the users can not log out.”) then you have a true bug on your hands.

3. You know what they say about ASSumptions. . .

We recently had a project that included a form with a text field for entering a date. The PM and stakeholders assumed that this field would have a date-picker (calendar control) fly out when gaining focus, but this was never documented in the functional specs or shown in the wireframes. As a consequence the developers simply made it a text box that validated for a date and moved on. The QA team signed off on this because, after all, it met the requirements of the functional spec.

During UAT, the stakeholders were visibly irritated that there was no calendar control for this field and the issue got bounced back to development as a bug. Was it a bug? No. It was an assumption made about which design pattern should be selected by the development team and never documented. 

If a requirement is important, the PM should be certain that it has been included in either the functional or non-functional specs. If that doesn’t happen, the issue should simply be labeled as an “enhancement” and prioritized in the backlog.

4. Not all bugs are in the code

Occasionally, an app that was working fine will suddenly display several prominent bugs causing a five-alarm fire among the maintenance engineering team. This is very rare, but it does happen. Almost without fail, we have found that the cause of this can be down to a change in the code’s dependencies rather than a defect with the code itself. A few examples:

• A DBA makes a change to the schema of a production database. The DBA thought this would not be of consequence–they simply changed the datatype of a column to save space, or dropped a column that contained no data. Unfortunately this type of issue can have an affect on the code and should always be discussed with the development team before such changes are made.
• A third party API on which the code depends has gone down. For example, there are APIs that calculate sales tax for eCommerce apps. If that API is having an outage, or has bugs of it’s own, then it can make the app consuming the service break.
• A maintenance engineer updates dependencies or frameworks without consulting the dev team. The app breaks. Again, any changes to software connected to the app should be thoroughly discussed with the engineers before they are implemented.
• The app is migrated to a new server that does not have all of the necessary dependencies installed.

Essentially, this one is all about communication. If any changes are to be made that might affect the code, they should be discussed beforehand. The primary engineering team should include a dependency profile with their turnover documentation to provide greater visibility into potential issues for the maintenance engineers. Also, there should always be a backout plan when making such changes.

5. Software can be hard

This may sound simple and silly but it is valuable to remember. The software game is full of risks–that’s why the financial rewards can be so high. It is a complex game with layers upon layers of systems and considerations. You should always allow time in your plan for things to go wrong so that when they do, you can have enough time and budget to step back, carefully consider whether what you are seeing is a technical defect or just the product of an evolving vision, and then properly label the issue.

At Polyrific, we take pride in the fact that we invest ourselves fully into our client’s projects. We know how this game is played and we know how to shepherd our clients through the process directly because we plan for and deal with issues, like bugs, that will inevitably come up. 

If you’d like to discuss your vision for a software product, please do not hesitate to contact us.