Lessons from my time in software support

As my time in software support comes to a close, at least for now, I am drawn to write down some write down some “lessons” I have learned over the last decade.

These words are my own and don’t represent the opinions of any company I have worked for.

Leverage text formatting to its fullest extent

Text formatting is key to communicating effectively over a written medium (support tickets, GitHub Issues, etc.). Even if you are not lucky enough to have access to a rich text formatting tool like markdown, even plain text/email can stylistically imply text formatting and document structure without extravagant formatting features offered by markdown.

Quotation blocks, lists, code blocks, are all understated tools to help your reader understand what you are communicating.

Quotation blocks can be used to explicitly indicate what you are replying to or to send documentation excerpts directly. Lists are great for steps that the customer should take, or reasons something happened, and so on. Code blocks can be used for more than just code, it works great for example terminal output. Finally, horizontal rules can be great for visually compartmentalizing a complex message with more than one topic.

Consider when a customer asks you multiple questions in the same email/ticket. How do you reply to them? Is it clear what you are replying to? Even lightly experienced support reps and those that work with customers directly will know this pain all too well.

Effective and intentional document formatting will help you overcome communication problems like this and more.

Consider a made-up support ticket:

I am having a problem logging in.
It takes forever and I never get logged in, then it gives me an error message. 
Also, I need help understanding my billing report? What do all the acronyms mean?

The customer has hit us with two questions out of the gate. There are two reasonable approaches to handling this.

You might consider an organic approach by referencing each question in the subject of your sentence:

Hi!
Can you please attach a screenshot of the login screen when you have an error logging in? 
The documentation for [the billing report has a table listing all the acronyms and their definitions](link).
Could you please let us know if that documentation answers your questions? 

This makes it more natural, and works for simple questions, but it can break down in complex questions and topics.

An alternative approach is to explicitly quote and reply to the customer’s statements and questions:

> It takes forever and I never get logged in, then it gives me an error message. 

Can you please attach a screenshot of the error? 

> Also, I need help understanding my billing report? What do all the acronyms mean?

The documentation for [the billing report has a table listing all the acronyms and their definitions](link).
Could you please let us know if that documentation answers your questions? 

With this approach, we are explicitly indicating what we are replying to. It’s more robust since it can accomodate more complex questions and answers. It can also accomodate a higher volume of customer questions; though, there’s an argument to be made that these questions should be separate tickets.

Optimize your own workflows

Most people will not have the same workflow or desire for the same tools, and that’s ok.

Sandbox environments are key to confident and accurate support

Hands on replication ensures that things are operating as documented and shed light on that which is undocumented.

Creating sandbox/test environments should be fast and easy, requiring little effort to replicate what a customer is writing in about. When it can’t be fast, it should at least be easy.

The empathetic support person will ensure that replication of the problem is a standard piece of their toolkit because it enables them to be confident in their instruction to the customer. If you can see the system’s behavior and nuances first-hand, you are enabled to give much more accurate, knowledgeable, and professional support about it. You can confidently state that when X action is performed Y happens.

Support will always be a part of documentation lifecycle

When a documentation team doesn’t exist, support is the documentation team. When a documentation team does exist, support is still an important part of the documentation lifecycle.

We’ll hear support people complain about documentation throughout our support careers. What is often missing from the discussion is the fact that support as a function exists to identify and rectify a business’s problems. That problem might be a bug, an unsatisfied customer (known feature limitations), or substandard documentation.

GitHub and other companies make efforts to open-source documentation or provide features to “vote” and add comments to documentation. This no doubt helps identify which documents need more attention, it doesn’t eliminate the need for support in the ecosystem.

Customers generally assume documentation is correct and accurate. This leads to a situation where a customer believes they have done something wrong or are experiencing a bug; these are both situations where opening a support ticket is expected and encouraged. However, the reality is that neither are true - the documentation is simply not up to par.

Even when customers know the documentation is wrong, they desire a human to reach out to. They want to describe how and why it is wrong, and they yearn for your advocacy and expertise to correct it.

Often, a customer will believe the documentation is wrong, but upon further examination, we can see that they have misunderstood the documentation and need more guidance. Repeated instances should still be treated as a documentation deficiency by the support person, there will generally be a reason that documentation is misinterpreted, and it can be improved.

Do not thrash against software bugs and poor documentation

A fallacy emerges in many support peoples’ minds at some point in there career. This fallacy is that all bugs are avoidable and that all documentation can be perfect.

This is empirically false for reasons that a support person without a background in software engineering may not be exposed to.

• Automated tests don’t catch everything.
  • These tests must be written and can miss things in the same way as any other software bug.
• Documentation can only be reviewed so much.
  • Dedicated technical writers, if you are lucky enough to have them, are rarely hands-on with the products they’re documenting. It is inevitable that information be missed during the transfer from technical people to technical writers.

These are some reasons why GitHub advocates to “Ship to Learn” internally. The best people to advise you of problems in your product are your customers, so getting their hands on the product and documentation is key to understanding its shortcomings. support people play a vital and valuable role in this process, as they are often the exclusive channel which feedback is received.

Am I advocating to devalue or discredit automated testing or review processes? No.

Responsible devsecops processes and techniques to reduce friction and identify problems earlier are important pieces of the modern software development lifecycle. These techniques do not catch everything, especially not the more human problems relating to documentation or semantic bugs or product feature gaps. support still plays a key role in identifying and rectifying these more nuanced problems.

Be kind and invite dialogue with customers

Customers will treat support tickets as transactional unless you explicitly inject kindness and dialogue. This can lead to frustration from weathered support people. It can feel as though you are treated like a question answering and problem solving robot without feelings of your own.

When this happens, take a step back and objectively review your work. Are you outwardly behaving like a question answering and problem solving robot? In my career, I’ve developed a set of rules that I intentionally follow in my support interactions to ensure I come across as human as possible.

Explicitly invite dialogue.

Customers may never follow up when you resolve their problem. They may never send you a thank-you. If you find yourself repeatedly lacking closure, ask yourself if you are outwardly inviting it. For example, “please let me know if you have any questions” or “please let me know if that works for you!”

When you explicitly invite further dialogue, you establish a social contract that people feel naturally obligated to respond to.

This doesn’t solve how support is culturally seen, and how some people will behave towards support no matter what, but it does help with warming and humanizing your interactions, hopefully improving customer and personal satisfaction in the process.

Exude a friendly professional tone. Talk like a human.

Use exclamations liberally. Say “please” and “thank-you”. Be empathetic - say “I understand”. Organically restate the customer’s problem to communicate that you understand the problem.

All together

This all takes tact, and the advice shouldn’t be blindly followed as you run the risk of sounding even more like a robot. However, when done properly, I’m a firm believer that it improves the overall reception of your words.

I’ll leave you with a simple, and perhaps unrealistically simple, example - first let’s look at the robot, but “correct” reply.

Hello, The procedure for downloading the audit report is to first enable auditing. The reason you aren’t seeing events is because you have only enabled it recently. Only events that occur after auditing is enabled will be available in the report. Regards,

Sounds right? But it can be more human.

Hello Paul, Thank you for reaching out! The procedure for downloading the audit report is to first enable auditing. The reason we aren’t seeing events in the report is because audit reporting has been enabled recently. Currently, only events that occur after auditing is enabled will be available in the report. I understand the frustration here, and I have submitted a record of this feedback to our internal teams to see if this process can be improved at all in the future. Like you mentioned, I’ll also check with our Documentation team to see if anything can be improved in that regard as well. Please let me know if you have any additional feedback or questions. I’m happy to dive into it further! Regards,

This isn’t a real or perfect example, but hopefully it gives you ideas for how to improve your own writing.

BONUS: did you notice the edits to the “answer”? Let’s review:

… The reason we aren’t seeing events in the report is because audit reporting has been enabled recently. Currently, only events that occur after auditing is enabled will be available in the report. …

First, we include ourselves in the problem by changing you to we - we implicitly put our skin in the game, suggesting without saying it that this is a collaborative process.

Next, we remove accusatory wording by being indirect and saying audit reporting has been enabled instead of you have only enabled it. Every customer dissatisfaction instance should be outwardly treated as a product gap, and not the customer’s fault (even if it is their fault 😉).

Finally, we add currently, further cracking open the door for further feedback. We want to imply that this is the way it works now, but it could work differently in the future. We implicitly invite conversation, and we lean further into the collaborative head-space by removing more adversarial indications.

Do not dwell on or entertain toxicity

My last note is one that is easy to say but difficult to actually do.

Leave toxic interactions behind as fast as you can. Otherwise, it will eat you alive. Interactions with toxic people is the worst part of an otherwise enriching and rewarding role.

This applies to both internal (colleagues) and external (customers) interactions.

Internally, Support is all too often a barrier of social competence between customers and social ineptitude. Externally, you will handle the burden of customers’ disappointment, dissatisfaction, and overall dislike towards support, the company, and the product. It is easy to take it personally - don’t.

Focus on the positive interactions. Let toxic interactions leave your memory and concern - they are not worth your time.