Poorly written Email, Bugs Reports etc.

Writing by shivdev on Friday, 17 of September , 2010 at 8:47 am

I’m one of the “fortunate” one’s to receive 50+ work emails on a good day. Really! And I’m a developer. OK I’m part of three teams and need to interact with 3rd party support as well, so on a busy day, I can get up to 150 emails easily. Balancing development between two products is fine, but now also dealing with email gets annoying. Even though most of this email doesn’t even concern you, it often distracts you and could impair your train of thought.

So, your mind gets tuned to skimming through the “junk” and trained to pick up just the right information quickly.

In a previous life, I saw this type of a Bug Report from a user (say John Doe) of the product who was not a developer. I’ve totally changed the content and the bug, but the format of the report is similar to what happened. Assume, I’m a UI developer and develop widgets and users can display data onto some highly customizable Table Widget.

Subject/Header:
Swing: Table: UI doesn’t show data

Body:
The Table UI is broken. The Table is not showing any data with currency formatting applied. We’re trying to display information about the total sales that happened per quarter across all regions. There are three regions of concern APAC, EMEA, North America and LATM and four quarters Q1, Q2, Q3 and Q4. The customer needs to see roll ups of all these values and given the large number of sales that have happened in North America they also want to see counts of number of sales rolled up. We issue a SQL and pass it through the “ABC” scripts/rules to transform the data and send it to the table. The second column in the table has been rendered to display currency. The admin guide doesn’t talk about rendering data that is transformed and displayed. Jane Doe stated she passed some more data through from the SQL to the table and did something with a properties of the table and changing it to currency format worked. But it’s not an option to change the rule. Currency capability must be a supported capability…product is very confusing to use. The weird thing is that in the Script’s Reference manual there is information on setting currency for the table (why information like this isn’t in the Administration Manual I don’t know). I searched google and it seems straight forward to apply rendering on a table. Various other formatting was tried without successful results.

Bottom line: Every table needs to support currency formatting. I should be able to provide a sales numbers, or sales estimates or whatever to accomplish what I want.

John Doe

Three things are important.

• The Subject: Table UI doesn’t show data
• The Opening Statement: The Table UI is broken. The Table is not showing any data.
• The Conclusion:Every table needs to support currency formatting. (notice how they use “Bottom line” to re-emphasize this)

These points indicate that the formatting on the table is broken, even though everyone has seen currency formatting working in tables on other screens.

So, is it really the table that’s broken? Could the problem be else where? Does the SQL look right? Are you allowed to use the “ABC” rule/script?

In this case, let’s say the problem was that the SQL was sending some incompatible result into the “ABC” script and hence was throwing an exception and not sending any data to the table and the user is notified of this as well as the detailed exception is in the logs. Now, this rule is mentioned only ONCE in the entire bug report while all the blame is on the Table. (BTW I’ve shortened the bug report, but it really had far too much more irrelevant information)

So, why then provide unnecessary information about the business of sales in EMEA, APAC, etc. and about the Q1, Q2… which doesn’t even concern the developer who’s getting 150 emails a day? To troubleshoot the problem, the developer might have to setup the same environment and try to replicate it when currency formatting always worked. Then finally, in all the mess find out that it’s this “ABC” rule that’s incompatible?

In good faith, the developer will assume given such a report that the advanced users knows what they’re doing and that the SQL and “ABC” rule are fine! If the table supports currency formatting the bug will be closed as not reproducilble! And then later on after some comments in the bug, Mr. John Doe claims that this bug report is for the rule “ABC”.

So, why not say?

Subject/Header:
ABC script doesn’t work with the following SQL

Body:
Passing a SQL “SELECT columnA, SUM(columnB) FROM tableA GROUP BY columnA” into the script “ABC” results in an ArrayIndexOutOfBoundsException.
Logs attached, See snapshot for details.
Easily reproducible.

Simple. No mention of the Table and currency formatting to totally mislead Development. Even if the steps to reproduce are not provided, the developer could figure this out simply looking at such a report.

I can’t discuss the actual scenario, which was a little more involved but as obvious as this example.

But, the point is to keep the content of your email, short and sweet while still providing all the relevant details. Not so hard to do, is it?

Leave a comment

Category: Rants/Raves

• Add this post to
• Del.icio.us -
• Digg -
• -
• Tweet -

No comments yet.

You must be logged in to post a comment.