Disclaimer

I produced this document to implement a support-driven development structure during my time as a DevRel lead. The team was considerably larger, so it was easier for the engineers to dedicate a percentage of their time to doing support. I suggest using this document as a source of inspiration and best practices, taking ideas here and there and adjusting them for your team size. Moreover, it has great tips for engineers who are not accustomed to talking directly with users. That part was probably what I found most useful when using this.

Goals

• Better measure the Community & support load
• Minimize support load overhead on the engineering team
• Ensure that product feedback is recovered and the feedback loop closes as rapidly as possible
• Lower the entry boundary for engineers to participate and engage in the Community
• Introduce a documentation-first approach to reduce the overhead of maintenance
• Improve user engagement and community stickiness

Introduction

Community Relations are 80% Acknowledging an issue and 20% fixing it.

~ Anonymous

The Community provides a trusted environment for our users, developers, and partners to get answers, share ideas, collaborate, and learn best practices to help make their time with us as successful as possible. Our engineers play a vital role in the success of the [COMPANY X] Community by welcoming new members, contributing helpful content, and building trusted relationships.

We must maintain this great tradition and grow the Community in any way possible.

The Community provides us with

• Word of mouth: Happy users talk to each other.
• Product Feedback: We are rapidly developing our product, and without the rapid feedback loop a community can provide, we essentially are blind.
• Quality Assurance: Rapid discovery of bugs before they create a significant production incident. Trust and Credibility are hard to develop, and they take a split second to demolish.
• Rapid Learning: Helping users out is an easy and fast way to get to know our products. Understanding our products from a user perspective is essential to “get” what we are trying to achieve. We are engineers, not code delivery cogs.
• Accomplishment

Support at [COMPANY X]

The [COMPANY X] products are free. Thus the support that we provide is community-driven. It means that the products are offered “as-is” while the team is engaged with users to help them become successful in bridging with [COMPANY X]. Our core focus is to get as much feedback as possible while offering a superb user experience. The main driver for support should be the Community itself.

Forum

How to organize the forum categories:

Each category has an “about” topic, with a paragraph about each category’s goal.

We should know each category’s goal to spot irrelevant topics and place them into the correct categories.

GitHub

• Used for Issue tracking
• Used for contribution:
• • All public repositories of the [COMPANY X]xyz_ organization.

Forum checklist

To facilitate engagement with the Community, please ensure that:

• Your account is associated with the company email. This is required to automatically add you to the “[COMPANY X] team” group.
• You log in using the Google Oauth option.
• You log in using a username/password combination but using the company email.
• You log in with another email but have added an alternative email.
• You request an administrator or moderator to add you to the appropriate functional group.
• Your account has a profile picture and a short bio.
• You join the #discourse-support slack channel. All new topics and posts from the categories (support, support-agent, support-cloud) are mirrored.
• You have familiarized yourself with the [COMPANY X] Community Code of Conduct that governs interactions for all members.
• You are familiar with the Discourse platform; We suggest these resources:
  • Discourse New User tips and tricks
  • Discourse New User Guide

Support

Channels The main support channel we currently have is Discourse. If the user needs to send sensitive information to the team, the user should use Discourse direct messages.

Moreover, we use GitHub for bug tracking so that users can follow our progress and stay up-to-date with bugs that concern them, or they can share information to help us solve a bug faster.

Support is being given in the Support category of the forum. We can divide the support into different sections based on the target user. For example, a lot of tools have both consumer users and developers. The first uses the product as-is, and the second builds on top of it.

It’s essential to think that every new category we add is taxing for the user and clusters the Community into small, non-viable clusters. Ideally, we want everyone to be in the same pot to reach that critical mass more efficiently. There is a reason why telegram groups are much more successful (in broad terms) than Discord and why well-curated telegram groups have better Signal-to-Noise ratio. Finally, we use tags to segment the issues further and make future reference easier.

Tags

✅ A list of all the tags we use can be found on the Community forum. We should make sure that all topics are correctly tagged for future reference.

As members of the group [COMPANY X]-team’ we can edit topics, so we should contribute to maintaining the forum. To learn more about tags, please read this comprehensive guide to Discourse tags.

Forum Tools

Whispers

Whispers are messages that are only visible to the group members. This functionality can chat privately on the forum topic without using another platform ([COMPANY X] ‘s slack channel). It enables the engineers to have all the information regarding the particular subject in one place so that future [COMPANY X] team members can easily access it. (If the chat happened over slack, the information would have been lost).

Read more about whispers in the Discourse documentation.

Topic Templates

We use topic templates for some of the categories on our forum. Read more about topic templates the Discourse docs.

Discourse Groups

Each [COMPANY X] employee belongs to a discourse group based on their functional group or Area of Responsibility. This is used so that the [COMPANY X] team can ping the appropriate group to care about a particular support issue that may demand more advanced knowledge.

All [COMPANY X] employees automatically belong to the group [COMPANY X]-team so that users can easily spot who belongs to the company and who is not. (It adds a small visible icon in the avatar). Moreover, [COMPANY X] members have the highest possible reputation level to effectively moderate the discussion (edit topics, change categories, remove, etc.).

We will enrich this list of Areas of Responsibilities as the Product/Engineering organizational chart evolves. The process is agnostic to how the [COMPANY X] team is organized into different sub-groups.

An example

Let’s assume we have these Areas of Responsibilities:

• GUI
• Contracts
• Infrastructure
• Protocol
• Community
• Marketing
• Ops/Hiring
• Product

We will organize the forum as follows:

• Only Admins and Moderators can message and mention a group.
• Each team member belongs to a discourse group according to the internal company structure
• Team member groups are only visible to Admins, Moderators, and group members.
• Groups and notifications
  • All engineers are subscribed by default to watch the Support category.
  • All engineers are subscribed by default to track the following categories:
    • Feature Requests
    • Support
• The @x group is subscribed to watch the [COMPANY X] company-specific-category category.
• The @[COMPANY X]-marketing group is subscribed to track the categories:
  • Community Guides
  • Announcements and Roadmap
  • Community
  • [COMPANY X] Content
• Moderating on Discourse
  • All [COMPANY X] employees have moderating capability.
  • We are expected to be accustomed to moderating a Discourse forum. Reading the Discourse Moderation Guide might help.
  • Read more about how to:
    • Assign a topic
    • Add an alternative email

How do we handle an issue?

As an engineer and [COMPANY X] team member:

• Verify that the issue belongs to the platform where it is created:
  • [COMPANY X]xyz_/: bugs
  • Forums: feature request
• If the issue needs to be submitted to the correct platform:
  • If it’s a support request, a feature request, or an idea/discussion on GitHub, we close the topic and ask the user to create an issue in our forum.
• We link the appropriate category directly so the user can avoid assuming the category they should post.
• If appropriate, we request additional information to be submitted to speed up the troubleshooting process.
• If it’s a bug report on Discourse:
  • We submit a bug report to the appropriate GitHub repository and link the issue to the forum topic.
  • If relevant and appropriate, we invite the user to help the [COMPANY X] team fix the bug by continuing the discussion on the GitHub issue.
  • As far as the support process is concerned, the support ticket is triaged since we have identified the root cause to be a bug and the fix to be the hotfix for that particular bug.
  • We then proceed to close the topic.
• If the issue is a new topic on Discourse:
  • Verify that the topic belongs to the correct category and sub-category and is tagged appropriately. We move the topic to the correct category and sub-category and tag it correctly if necessary.
    • Instructions on how to add a tag to a new topic: docs
    • Tag groups and explanations: Tags
• Verify that the user has used the template for the specific category:
  • If the user hasn’t and, as a result, omitted important information. In that case, we ask the user to fill out the missing information to speed up the debugging process.
• We Respond to the user.
• We assign the topic if:
  • We want to handle it later on personally. We respond to the user we will reply to later, assign it to ourselves, and the rest of the team knows it is being handled.
  • We are team leaders and want a team member to take on a particular topic.
• If the Discourse topic is a question or request for assistance, we triage the user issue.
• We ensure that our responses align with our documentation-first approach.
• Finally, if it’s a support topic, we ask the user to mark the post that solved their question.
  • In contrast to GitHub, the lifecycle of a support ticket (topic) ends when a post is marked as the solution, either by a moderator, an admin, or the original poster (OP).
• If we are unsure whether we should engage further, we should be aware of the limits of our support process.

How do we triage a user issue?

As an engineer and [COMPANY X] team member:

• It’s better to start by searching the forum in case the question has been asked before
• Try to find the answer in our documentation and/or GitHub.
  • Start with google since it could have been indexed, so you save time.
  • If Google doesn’t provide anything, search individually:
    • [COMPANY X] Docs
    • [COMPANY X] GH issues
    • ??
• If you find an answer, link the resource and explain why it is relevant to his/her issue. If it is complex, we should walk the user through it, even if it’s evident to us. Even competent engineers tend to think in different ways. Thus something intuitive to one may not be for the other.
• If we are still looking for an answer, we request more information.
• If this requires specialized knowledge, we ping the appropriate team in Discourse.
  • For example,
    • The GUI team would better handle a possible UI bug.
    • If the user discusses features and how they should change/improve, maybe the @[COMPANY X]-product is the appropriate group
  • Until the group acknowledges the handover to a colleague, we ensure that you keep the user updated regarding the status of their question. To do this, we click the bookmark icon and set a reminder for the topic.
• If we believe that we have found a bug, then we open an issue to the correct bug tracker and link back to the GitHub issue in the topic so that the user can follow its resolution.
• We proceed to set a reminder to the topic with the bug so that we can revisit it every X days(e.g., weekly), and in case the bug is resolved, we ping the user that the bug was fixed, asking them to test it.
  • In case of everything works, we mark the topic as “solved,” and the support ticket’s lifecycle is concluded. To do this, we mark a post as “solution”.
  • If the user continues to have problems, the initial triage wasn’t accurate, so we need to proceed and triage it further.
• Read more about how to:
  • Mark a post as a “solution”
  • Set a reminder for a topic

What are the limits of our Support process?

Generally, whatever is related to [COMPANY X] is a fair question for a user. More often than not, the discussion will touch on broader concerns, applications, and issues, which may not be narrowly relevant to [COMPANY X]. Generally, we want to foster discussions about all things interesting to us and the users, so we want these discussions.

At the same time, our support process, being community-led, has its limits. If we can’t engage further in the debate, we should clearly say so, but at the same time, invite other users to join the discussion and share their opinion. The importance here, as always, is to be kind, direct, and close the loop, setting clear expectations on whether the user should expect an answer.

How we respond to users

• We write short and sweet responses. No need to write a lot, but we are kind.
• Don’t be too short; Avoid “Yes” and “Yes, thanks.”.
• We are honest; if we don’t know something, we say so. If we need to do some additional research or the help of a colleague, great, we ping them. Nobody expects us to be omnipotent and omniscient.
• We share the debugging experience with the user, i.e., what we tried and the results we got. Our users are engineers, which means that they are curious people. They are as interested in solving the problem as they understand what went wrong and how you solved it.
• We address all the points of the users. Using bullet points works for everyone.
• We make sure that we acknowledge how they feel.
  • e.g., “I understand that this is frustrating, but don’t worry, we are on top of it!” Source

Example for points (1,2)

Question

Will you do something about this unexpected behavior?

A1

Yes.

A2

Yes. I have already shared the feedback with our team. They are going to check it out. Thank you so much for taking the time to share your feedback with us!

A2 is the better response.

Example for point 3

This does not always happen, but when it does, it does not let me do X. I expect to be able to do X since other products allow me to do it, and your product will enable me to do it in some cases. Is that normal?

Hi! I don’t know why this happens sometimes. It may be unexpected. I will investigate this and get back to you. That’s undoubtedly not ideal, but if you do Z, you may achieve what you need. I hope that helps. Cheers, Odysseas

This response addresses all points:

• It may not be normal → “Is this normal?”
• If you do Z → “I expect to be able to do X…”.
  • It is a workaround. It could be better since the user would like to do X.
• I don’t know/will investigate → “This does not always happen. It does not let me do X.”

Point 4 - Empathy

If the user contacts us, it means that the user got affected by our product positively or negatively.

The user never fails; it’s always the fault of the design, which did not consider the possibility of a human error. There is an exciting Stack Exchange answer regarding this notion.

So, it doesn’t matter what the fault is. For a split second, the user’s feelings got hurt, and he got negative emotions because of our product. Let’s try to change that!

Empathy

Empathy is the skill of being able to understand the feelings of another person. The thing is, it’s not very easy, and when we do have it, we have to communicate it actively. We have to show empathy.

Thank you for your feedback about your interaction with our team yesterday. And sorry you didn’t get good support from us.

For some reason, the user said that they were unhappy with the communication they had with our team. That’s fine. Listen to the feedback they will give ( you might have to ask for it) and then consider it internally if it’s credible or not.

In all cases, acknowledge that they were unhappy (..sorry you didn’t get good support..). Acknowledging is NOT agreeing. It’s just acknowledging. Showing that you understand, not that you agree. That’s sympathy. We focus on the fact that they believe they had terrible support, not that we gave awful support. Even if the user takes it as admitting fault, that’s OK. Be the bigger person.

Of course, if you agree with their verdict, say so. It will only improve the relationship.

Keep the user in the loop

• We strive to keep the users up to date, even if their issue still needs to be resolved.
• When possible, it’s better to do the work for them.
  • e.g., We should open the GitHub issue if we find a bug while debugging a user’s problem.
• We ensure that we circle back to the user every few days so that they know that we still remember their issue.
• Even if we have not had time to pick up the bug, we should let the user know. We work in an industry where the rapid change of priorities is to be expected. Transparency, again, is critical.

Dos and Don’ts

• We don’t share company and financial secrets( e.g., Revenue, Growth, Pricing, Unannounced customers/users, undisclosed security/performance issues.
• We don’t make forward-looking statements (e.g., Feature release, product strategy, and prioritization)
  • The single source of truth for this is our Public Roadmap. If we are unsure, we ping the product team for clarification.
• We are honest and transparent.
• It’s better to wait a bit before jumping into a conversation. It’s essential to give the community space to respond to a question. Moreover, experienced engineers should allow the newer engineers to engage first so they can learn about the product first-hand.

Documentation-first approach

Excellent documentation is a great way to improve the developer experience and lower the support load, as users can become successful even when they find friction. This way, our users can get the information they need without relying on the Community or the [COMPANY X] team to help them.

• When learning, use the docs.
• When troubleshooting, use the docs
• If something is missing, update the docs.

Moreover, this approach ensures that our documentation is always the single source of truth and that users are aware of the docs we have.

• We prefer to respond with links to our docs.
• If the docs are missing, we create them and link the user to the PR.

Finally, if you encounter a particular support case that you believe has value, please ping the owner of the docs. We can create some content to help more users (e.g., a guide), so your help will be invaluable.

How do we handle Feature Requests?

Feature Requests are handled by the product and community team handle Feature Requests, so it’s not part of the support process.

The support agent is invited to engage freely with the users in the Feature Requests category, but we shouldn’t:

• Vote on Feature Requests since they are supposed to be 100% the voice of the Community.
• Make Feature Requests, but we should contact the product team and communicate our ideas/suggestions internally.
• Make commitments about implementing a feature that the Community has requested (e.g., “We should build that, it’s super”).

Tips For Engaging In The Community

Some general tips for engaging successfully with our Community.

Create Your Identity

To get the most out of the Community and build your network:

• Take five minutes to complete your community profile.
• Start by uploading your picture, description, industry, location, and products used.
• Take it one step further and link your social profiles, such as LinkedIn, Twitter, and Facebook.

Share Your Knowledge & Build Your Career

Grow your network and resume by contributing value to the Community through blog articles, knowledge articles, and sharing knowledge in discussion threads. The more you share, the more value you will add to your career journey by demonstrating your expertise.

Thanks to the power of SEO, your contributions will surface in search engine results for your name. Please make the most of it!

Like And Share Valuable Content

Help surface information by liking and sharing content in the Community and with your customers outside the Community. As product experts, our insight is valued by the community members.

Please do not like or share controversial content or criticisms of the company. Escalate as needed through the proper channels.

Join Relevant Groups

We encourage you to join and participate in virtual, local, industry, and feature-specific groups relevant to your experience and interests. Your presence in these groups will increase our members’ value and build their understanding of our products and services.

Use Search

One of the most common ways our members find great info is through a search. The search bar is located at the top of the page regardless of where you navigate the Community.

• In docs.[COMPANY X].xyz, the search bar searches across our entire documentation, corporate website, blog, and GitHub (not issues, though).
• In forum.[COMPANY X].xyz, the search bar searches the whole forum. Teaching other members how to search is also essential. ** Please do so with the heart of a teacher.**

Suggest And Vote On Internal Ideas

Your expert opinion matters, and we want to hear from you! Feel free to post, comment, and vote on ideas in the /product repository.

We kindly ask that you refrain from suggesting, voting on, or otherwise engaging with the external customer idea exchange unless it is your role to do so. It can look a little strange if employees are voting on ideas that are critical of existing functionality or strategic direction. Employee participation there could also be considered “forward-looking” information.

It’s OK to share that you feel an idea is exciting or you like the notion of a new feature, but we should refrain from saying, “that’s awesome. I hope we do it”. It’s a subtle line, but it shouldn’t restrict you from engaging freely.

KPIs

You can’t manage what you can’t measure. ~ Peter Ducker

Although the support is centered around community participation and is offered on an “as-is” basis, we have critical measurements for the Community as a whole and the [COMPANY X] team’s engagement in particular. The following metrics are being tracked:

• Time-to-first-response in a new topic: The difference in timestamps between topic creation and first post creation.
• Time-to-resolution in a support topic: The difference in timestamps between:
  • The topic creation
  • The post that was marked as the solution
• Solutions per [COMPANY X] team member: The number of posts of each [COMPANY X] team member which have been marked as “solution”.
• Solutions by Community members: The number of posts marked as “solutions” that do not belong to a [COMPANY X] team member.
• The number of topics and posts in the following categories:
  • Support
  • Feature Requests

FAQ

Include FAQ here that engineers can copy and paste to recurring questions, e.g. (“how [COMPANY X] is profitable, are you selling data????”)