$ less blog.txt
This page is still kind of buggy with the pagination and format. If you prefer, see an archive of all of my blog posts.

Communicating with Engineers: How to File Good JIRA Tickets


By Jonathan Tsai (@jontsai |

Original Permalink (working Quip doc) : Communicating with Engineers: How to File Good JIRA Tickets
License: CC BY 3.0

This article was originally written as part of a mini-training for the customer success team at Iterable in July 2017. For the most updated version of this article, view the Quip version at the above permalink.

Edit: This article also got published on the GoodAudience Blog.


“Those who fail to learn from history are doomed to repeat it.” - George Santayana

Engineers build things, and also fix stuff when things break. Everyone’s time is valuable, so how can we effectively capture and document issues that come up, so that we make the product better, and learn as a team rather than “repeat the mistakes of history.”

Common Pitfalls to Avoid

  • Conflating issues (that shouldn’t be conflated)
    • Symptoms:
      • Combining multiple issues into one JIRA ticket.
      • This is happening for me, too!
    • Why it happens: Upon initial inspection or cursory examination, two or more issues can appear to have the same cause. However
    • How this hurts: If all reported under one issue, we may solve one problem but unintentionally overlook others that got masked.
    • Recent examples: Emails being sent out slowly for Spotify
    • Actual root causes: Three separate issues, actually, with 3 different solutions
      • CloudAMQP memory failure
      • Unhandled exception in our messaging dequeuing code causes processor
      • Inadvertently downgraded date-timezone library dependency, which failed to parse a particular timezone
    • Recommended alternative courses of action:
      • Do some research to pinpoint when (time), where (context: app? mobile? API?), and how (what the user was doing)
      • Capture the major themes
  • Prematurely filing a ticket / fragmenting tickets (opposite of conflating issues)
    • Symptoms:
      • You’re filing too many tickets
      • The rate at which you open tickets far exceeds the rate at which they get closed or completed (optimal ratio is hard to specify, but maybe 3:1 or 5:1, but not definitely 10:1 or 20:1)
      • The ticket has already previously been filed
    • Why this happens:
      • Want to avoid conflating issues
      • Did not research if an existing known issue
      • Did not consult or check with other teammates
    • How this hurts:
      • Too many issues get logged, but never worked on.
      • Generates a lot of noise and distraction
    • Recommended alternative courses of action:
      • Talk to teammates and if at least 1 or 2 other CS persons agree it should be a ticket, or 1 other engineer, then file it
      • Do some research whether an existing ticket already exists. This may take more than a basic search or two. Scan through past 2 weeks at least, and search a couple of most likely specific keywords.
      • When it does happen, find the other ticket, enhance the ticket with more detail, and resolve one as duplicate.
  • Providing too much detail.
    • Symptoms: Parroting the exact request from the customer
    • Why it happens: You feel inundated or overwhelmed with customer requests, so you report them in JIRA or to an engineering Slack channel for assistance
    • How this hurts: CS is the first line of defense for engineering team, otherwise engineers wouldn’t be able to focus on making stuff better and spend most of the time troubleshooting. Engineers aren’t necessarily better problem solvers than CS, so they would start to feel inundated or overwhelmed, too. The engineer would have to
    • Recommended alternative courses of action:
      • Imagine you are a 911 operator/dispatcher. How would you field calls?
      • Do some translation or summarization of the actual issues at hand. No need to provide a diagnosis
      • Perform some high-level filtering, triaging, and pattern matching before filing a JIRA ticket or hitting up Slack channel
      • Ask a teammate or someone in person (counter-intuitive, yes, but a poorly researched JIRA ticket or Slack message disrupts more people, since N individuals need to read and process that message); an alternate could be using Direct Messages in Slack over blasting a channel.
  • Providing too little detail
    • Symptoms:
      • JIRA ticket is really short, or took you less than 10 minutes to create.
      • Engineer follows up with more questions. You answer some questions, and more questions are asked.
    • How this hurts:
      • And endless cycle of questions with no further clarity being established.
      • Or, the JIRA ticket never gets addressed at all, because it wasn’t actionable.
    • Recommended alternative courses of action: A good JIRA ticket:
      • Should take at least 5, maybe 10-15 minutes to create, if not longer
      • Is comprehensible by any engineer
      • Actionable. The problem is succinctly described, and it is clear what the next steps are.
      • Tracks only one issue or actionable item. Only has “one user story.”
  • Not filing a ticket
    • Symptoms:
      • You have lots of conversations about an issue.
      • You’ve already spent 20-30 minutes thinking or talking about an issue
      • You’ve already spent 20-60 minutes trying to address and issue on your own, and it is still not resolved
    • Why this happens:
      • You get caught up in the moment or simply forget
      • Not wanting to file too many tickets
    • Recommended alternative courses of action:
      • File a ticket!
      • Include a good title. A good title describes a course of action, rather than the symptom of the problem. Focus on solution, rather than the problem
      • Include a good description.
        • One sentence summary that answers several of “Who? What? When? Where? Why? How?”
        • A short 2-4 sentence paragraph of the expanded problem and proposed solution
        • Any supporting details in a bulleted list
          • Links to the actual issue in the product or app
          • Links to customer conversations, Slack conversations
          • Links to supporting documentation
        • Additional attachments, key snippets of conversations or key pieces of “evidence” gathered or research performed, or troubleshooting steps already taken

Choosing Good Titles

This is one of the MOST IMPORTANT things you can do. You may not think it, but software engineers spend a lot of time reading every day. Reading code, reading tickets, reading Slack, etc. Therefore, choosing a good title for the ticket will have significant effect on comprehension and speed of delivery.

A good title:

  • Describes a course of action, rather than the symptom of the problem
  • Describes the MVP. Some people like to write user stories, but I’m not a fan.
  • Usually starts with a verb, stated in the form of an imperative, as if authoritative:
    • Simply, “Do this” is much preferred to “Can you do this because So and So needs this or that?”
    • This is not rude; it’s succinct and to the point
    • The reasoning and background should go in the description.
    • Engineers can push back or discourse on it in the comments, with their own reasoning
  • Important: No verb implies no action, and therefore, none will be taken.
  • JIRA ticket titles should not be nouns, generally.
    • For new features:
      • Bad: Facebook Custom Audiences
      • Good: Implement Facebook Custom Audiences
    • For improvement or requests:
      • Bad: IP Whitelisting
      • Verbose: Customer X is asking for a set of IPs or an IP range that they can whitelist when it comes to receiving webhook posts
      • Good: Provide Fixed IPs for Webhook Servers for Customers to Whitelist

How to pretty print JSON from CLI


Software engineers frequently have to deal with JSON and inspect or manipulate it.

There are two easy ways of pretty-printing JSON from command-line to aid in visual inspection. The first requires no installation, and the second requires a minimal installation but also provides syntax highlighting and manipulation capabilities.

Method 1: Using Python - Nothing to Install

Optional: Add alias to .bashrc
alias json='python -mjson.tool'


$ echo '{"cool": { "story" : { "bro" : [1, 2, 3] } } }' | json
    "cool": {
        "story": {
            "bro": [


Method 2: Using JQ - Minimal Install

Mac install via Homebrew: brew install jq
Ubuntu install apt: sudo apt-get install jq

$ echo '{"cool": { "story" : { "bro" : [1, 2, 3] } } }' | jq .
    "cool": {
        "story": {
            "bro": [


If you start learning to code in your mid 20s, can you make a good living off it?


I know of several people who start learning to code in their mid 20’s, and are doing fine now.

However, it’s very subjective what a “good living” is.

Compared to the rest of society, programmers (anyone who writes code) and software engineers (a subset of programmers, with more emphasis on “engineer”) might make a relatively higher salary.

However, just as with any field, there are different grade levels, and how well you do depends on what level you are able to attain, and that has a correlation to how much time you spend working on your craft.

If you work hard and dedicate yourself to software engineering now, you can probably make a decent living in 2–3 years. Whether that will exceed your earning capacity in whatever other endeavors you may try, or are currently in, varies widely depending on your individual background, circumstances, opportunities, and experiences (and ability to grow in all of those).

I think it may take 10–20 years of smart and hard work to get to the top tier of any field, software engineering included.

If you’re able to keep your head down and stay focused, go for it. If you’re easily distracted by others around you and are discouraged by others who seemingly effortlessly have more success than you, this may not be the path for you.

I have one friend who was working in the field of tech and executive recruiting, who was considering a switch to software engineering when he was already in his early thirties. I quoted to him a proverb, “Do you see a man skilled in his work? He will stand before kings; He will not stand before obscure men,” and he decided to stay the course and excel in what he was already good at. Fast-forward two years and he’s now crushing it as an executive recruiter, making much more impact than he would have, compared to if he had switched his career to software engineering.

View original question on Quora

IntelliJ ProTips™: Start the IntelliJ JVM process with additional memory


Assorted tips and tricks for IntelliJ

Start the IntelliJ JVM process with additional memory

  1. Open the application once, normally, after a new install before editing this file.
    a. Otherwise, the signatures won’t match and the OS will think that the package has been tampered with, and security settings will prevent launching of the application. You will then have to delete the entire application and reinstall it.

  2. Quit IntelliJ (Cmd+Q)

  3. Edit /Applications/IntelliJ
    a. emacs "/Applications/IntelliJ"
    vi "/Applications/IntelliJ"

  4. Increase the following settings from their defaults (note: only works if your machine has sufficient RAM):
    a. -Xms2048m
    b. -Xmx4096m
    c. -XX:ReservedCodeCacheSize=1024m

  5. Start up and enjoy your upgraded IntelliJ on steroids.

  6. Note: These steps must be repeated after every upgrade.

Other options listed here:

Enriched objects


random: my new favorite coding adjective recently is “enriched”

val enrichedObj = obj ++ someAdditionalStuffs

reminiscent of / inspired by

Make a Donation