Avisi Blog

Good issues have good titles

Geschreven door Gert-Jan van de Streek | 27 September 2012

Finding bugs is an art. Reporting bugs should be considered an art as well. A well written bug starts with a decent title. Bugs with good titles can be classified or declassified in a glance.

A good title describes the problem, not the solution. It is short and sweet and always concrete. It tells what it is about and what is wrong and possibly even under what conditions it appears. To sum up: what, where and when. That is quite hard to do in a few words. Let's take a look at some examples, good and bad.

Good: After Upgrade to Confluence 4.1.9 the content in Edit-Mode appears in Wikimarkup (very clear what, where and when).
Could be better: Javascript errors while editing page (what!? where?)
Could be better: Problems with workflowreport (not very concrete about the what).
Good: Including a macro in the heading causes the link in the TOC to always take you to the first heading on the page.
Humor: "Edit in Word" will never work for OpenOffice
Ouch: Possible XSS issue (where? what?)
Another ouch: Issue with Office Connector (I am sure there is an issue... but what is it about?)
Awesome: "Edit in Word" fails to open Word when the page title contains double quotes (")

Yes, I know that issue trackers have a description field as well, but titles show up in dashboards, wallboards, Service Level Agreement report, release notes, etc. Do them well!

 

PS: On top of what / where / when, the best issue titles ever contain a compliment and some humor: