The importance of description

I was fortunate to have been assigned the much sought after Christmas (Well, just a couple days after Christmas day. Still counts.) article slot. Indeed, my colleagues must have realised after all this time what a jolly good, honest to heart, pleasant to be around fellow I am. So to reward them, instead of writing about Santa, I shall rant. Hooray!

 

Today’s rant’s main point of focus is one particularly crucial, and one that separates a smooth sailing day of work to one that grants you anxiety and makes you want to pull your hair. Ticket wording. That includes all things considered and not just your standard run of the mill procedure of issue reporting.

 

In an ideal sterile environment, it probably could refer to just that. Many teams that follow a test driven, agile if it sounds better to you, will tell you this is mostly not the case. Inside a ticket you will find decisions made, notes taken, descriptions, references to other tickets, even a photo of your ex. Which really shouldn’t be there. And if you do find it, you should definitely consider resigning.

 

Be descriptive, fear not to be verbal.

 

And slowly start being a bit less verbal, once you are sure about what you are doing. See, between reading a ticket that takes you by the hand and describes exhaustively everything step by step, and one that omits things, always go for the first. It will be a bit more frustrating to read, it may stretch your attention span a tad thinner, but ultimately it will provide all the information you need.

 

Being well informed is always better than missing pieces of information. Surely the ideal is to strike the perfect balance of feeding what needs to be fed and leaving the filler out of it. That is not an easy task though and you are bound, regardless of how good you become at it, to always lean towards being more or less verbal than needed. Be more.

 

Attachments are a support class

 

Attached files are really there only to further clarify and provide additional data, data that could *not* be simply written down in the ticket’s description.

 

Screenshots are ideal to showcase support text, and you should never be afraid to use them in order to support your description and enhance it. They also tend to reduce time needed for developers in order to grasp the issue’s whereabouts. Of course do not overdo it, this is a ticket not a gallery.

 

Videos are second in my chain of favor. They do have the additional strength of motion, which makes it easier to communicate the issue. Quite contrary to how images work though, they will most of the times take more time to process (depending on their duration). That is time removed from the main flow of the description, so be aware and never use too long videos. Another weakness is of course the size of such files, but this may or may not be an issue depending on hardware and network limitations.

 

Documents are the worst of them all. Unless they have data which is going to be used (for an example, imported to an application) you must never ever rely on them to take place of the ticket’s description. After all, there is no reason to nest a document inside what is essentially another document.

 

If it isn’t written, it should not be made.

 

And if it is made, it should get written down. Descriptions are there to include what needs to be done as well as what was done, and everything in between those too states. It is understandable that many times a developer will come across something extremely minor that could be fixed, while not in the description’s scope. There is nothing wrong with that, it is actually a good thing, they will think.

 

While intentions are honest here, even the slightest deviation could potentially render redundant a previously made ticket, for the problem that was fixed. It will also dillude the bug trail, making it harder to track down its source down the development line. In the worst case scenario, that minor fix could domino effect to bigger problems, ultimately costing a lot more time that it saved by being fixed outside of the loop.

 

Can you please stop ranting all around the Christmas tree?

 

Yes, I can. And I will. Merry Christmas and a happy new year 🙂

 

Comments

Contact Us Now!


Social Media