Define result-oriented docs-first Community Forum Support workflows
What is the problem?
We don't have any defined workflows for Forum Contributors.
Why is this a problem?
Forum Contributors not sure how to maximize their time and results.
Proposal
Define docs-first results-oriented workflows for GitLab team members contributing in the Community forum.
Glossary (acronyms and lingo):
- Community Forum - https://forum.gitlab.com
- Docs-first - docs-first methodology
- Docs-first approach to Support - Ticket Deflection through Documentation workflow
- FAQ - Frequently Asked Questions (from Free Users)
- FFUP - Frequent Free User Problems (common free user problems that generally require troubleshooting or technical support assistance)
- Forum Contributors Group - see gitlab-com/marketing/community-relations/general#23
- Free User Support - technical support or assistance provided by GitLab Support Engineers to Free/CE/Core GitLab users (not paying customers, prospects, or partners)
- RoI - Return on Investment - measurable results of investing time and resources
- SE - GitLab Support Engineer
- Silo - as in information silo, created when information helpful to others is sequestered instead of shared
Flowcharts (WIP)
Here is an old flowchart I created to track options on how GitLab users find answers/solutions:
GitLab Support Journey
The Search
Note: Paths to solutions/answers that end in Docs without support intervention can be used to help measure ticket deflection.
graph TD
A1(Question about GitLab) & B1(Problem using GitLab) -->
Y(Seek Answers & Solutions) --> A(Where?)
A --> b(Docs)
A --> c(Forum) --> F(Docs)
A --> d(Support) --> G(Docs)
A --> e(Twitter/Social) --> H(Docs)
A --> f(Stack Overflow)
A --> g(Third-party)
Asking for help
Free user Support journey
graph LR
A(GitLab technical problem question)
A --> C(Ask for help)
A --> D(Search for answer/solution)
C --> 1a(Support) --> 1b --> E
C --> 1b(Forum) --> E
D --> E(Find answer/solution)
D --> F(Don't find answer/solution) --> C(Ask for help)
Ideal Free Support Experience
Win-win-win - benefits GitLab community, customers, and team members.
-
self-serve support -
docs-first -
ticket deflection
graph TD
A1(Question about GitLab) & B1(Problem using GitLab) --> D(Search for answer/solution)
D --> E(Find answer/solution)
Docs-first
GitLab employs a Docs-first methodology to ensure our documentation is a SSoT resource where users can find answers, solutions, and information on using GitLab.
We employ a docs-first methodology to help ensure the docs remain a complete and trusted resource, and to make communicating about the use of GitLab more efficient.
- If the answer to a question exists in documentation, share the link to the docs instead of rephrasing the information.
- When you encounter new information not available in GitLab’s documentation (for example, when working on a support case or testing a feature), your first step should be to create a merge request (MR) to add this information to the docs. You can then share the MR in order to communicate this information.
The more we reflexively add useful information to the docs, the more (and more successfully) the docs will be used to efficiently accomplish tasks and solve problems.
GitLab Documentation is an extremely valuable resource in providing Customer Support and can be highly effective in assisting the wider community.
The library of docs.gitlab.com
is vast and can be hard to navigate, some library patrons will need assistance finding what they need.
GitLab Support Engineers use GitLab documentation and a docs-first approach to help answer questions and share solutions.
The docs-first approach to Support is codified in our handbook entry on Ticket deflection through documentation.
Ticket deflection through documentation
By building up a corpus of documentation informed by real-world problems we can ensure that customers can get the answers they need before they come into the queues.
- When learning, use the docs.
- When troubleshooting, use the docs.
- If something is missing, update the docs.
By developing a docs-first approach to answering, we can ensure that the documentation remains a highly useful single source of truth, and that customers are more aware of where to find content on their own.
- Always respond with a link to the docs.
- If docs content is missing, create it and link the customer to the MR.
Similar to GitLab Support ZenDesk tickets, unsolved GitLab technical support threads in the forum are often an opportunity to:
- link to relevant documentation
- improve docs based on user interaction/feedback
I propose all GitLab Support Engineers default to using a Docs-first approach to Support in offering technical support or assistance in the forum.
I also encourage Community Advocates, Technical Evangelists, and any other team members who assist in providing technical support in the forum to leverage a docs-first approach whenever possible.
Special types
In our documentation styleguide we define "special types" of content that are not well-suited for our documentation (Tutorials, How-to guides, Explanations)
There is demand for and value in offering this content, but the "no special types" rule has historically restricted GitLab from shipping this content in our official docs.
This type of content with a docs-first approach in the Community Forum could be the mortar that fills the gaps left in our docs as official SSoT.
Examples of Community forum threads where answers and solutions are "special types" that don't "fit" into the docs:
- Explanation - "I read the docs, but I don't understand."
- Situation-specific Tutorials/How-tos - ("I'm running GitLab CE 11.0 as a Docker container, and I want to upgrade to GitLab 13.2 EE Omnibus with minimal downtime, how can I safely do this?")
- Problem-specific Troubleshooting steps (I upgraded GitLab from 12.9 to 13.1 and now it's not working, I get 404 error on every page - please help!)
GitLab Support Engineer Modes of Work in Community Forum
- First Responder - Early detection/alert system - of problems, bugs, regressions that will affect customers
- Silo-breaker - publicly share solutions/answers common in free user support
- Fruit picker - low-hanging fruit = quick, easy wins
- Fishing Instructor - Self-serve Support
- Community Expert - involving experts workflow
- Documentarian/Librarian - (upgraded to default workflow instead of dedicated modes of work - see Docs-first section
First Responder
The Community Forum is an early detection and early alert system for problems that will inevitably affect customers.
GitLab FOSS makes up over 80% of the GitLab codebase. Any technical problems with this 80% of the codebase will affect all GitLab users, including customers. GitLab has well above 10:1 ratio for free users:customers.
In terms of detecting bugs, improving documentation, and identifying problems in our product that will affect paying customers, our community of free users is an excellent resource.
Free users can notice and bring up bugs, regressions, and problems with our product or docs in the Community forum before we get Support tickets from customers about them.
Silo breaker
Silo-breakers take common answers/solutions in Support ZenDesk and ensure they're available and discoverable to all GitLab users.
Support team members may notice patterns or trends in incoming Support tickets - new FAQs, increasingly common problems, confusion regarding a new feature, unclear documentation, or bugs affecting customers. We communicate internally, usually via Slack and Support Week in Review, to raise awareness in Support and help anyone who encounters tickets on that.
If these same patterns or trends are present in the Community forum, providing this type of answers and solutions to forum threads could help get answers/solutions available and discoverable via search.
Fruit-picker
Specializes in "picking" low-hanging fruit, or providing known answers/solutions to common GitLab user questions/problems with minimal effort.
- Quick, easy wins. ("I know the problem/question and can easily explain the solution/answer")
- The answer is in our documentation. (polite link to docs is sufficient)
- Single-touch Solutions. (no follow-up required)
Fishing Instructor
"give a [hu]man a fish, and you feed them for a day; teach a [hu]man to fish, and you feed them for a lifetime." - proverb
TLDR: It is more worthwhile to teach someone to do something (for themselves) than to do it for them (on an ongoing basis).
The forum is like fishing, "Toss in a Q, get out an A".
Fishing is "the activity of catching fish". To catch a fish, one must know how to fish, and where to find fish to catch. Some people hire fishing instructors or guides to help with this.
"Fishing instruction" in the forum is an opportunity to showcase the resources are available and how to find them. (docs, issues, MRs, codebase, forum threads). The forum is a pond with fish, and the goal of this role is to:
- make sure free users know how to fish
- direct free users to the best fishing spots
- keep our pond well stocked
"Fishing instructors" enable and empower GitLab users to catch their own fish - find solutions and answer questions without Support intervention.
By directing incoming Free user tickets to the Community forum, where fishing instructors are available, users get in the habit of finding answers/solutions outside of GitLab Support.
Self-serve support is the ability to find answers or solutions to technical problems by oneself. GitLab Support would consider self-serve support part of "ticket deflection".
Currently we have a lot of folks reach out to Support without first looking for easy answers/solutions.
graph TD
A(GitLab technical problem question)
A --> C(Ask for help)
A --> D(Search for answer/solution)
C --> 1a(Support) --> E
C --> 1b(Forum) --> E
D --> E(Find answer/solution)
D --> F(Don't find answer/solution) --> C(Ask for help)
We also have folks who contact Support although they are not a customer. By showing free users where to fish, we can reduce any delay and friction in Community support options.
graph TD
A(Question/Problem)
B(Customer?)
C(Y)
D(N)
E(Support)
F(Forum)
A --> B
B --> C
B --> D
C --> E
D --> E
D --> F
The most efficient and effective way to connect users with appropriate support option is to act in a way that encourages and increases the following support-seeking user flow.
graph TD
A(Question/Problem)
B(Am I a Customer?)
C(Y)
D(N)
E(Support)
F(Forum)
G(Success)
A --> B
B --> C
B --> D
C --> E --> G
D --> F --> G
Community Expert
Assist Community Relations with involving experts workflow for questions and problems where GitLab Support team is the expert.
Documentarian/Librarian
This dedicated role has been deprecated, as these docs-first will be an important part of all Support modes of work in the forum.
Continued in Docs-first.
DRI
@greg is DRI
I'll be collaborating and consulting with @LindsayOlson and David Planella on the Community side of things.
Desired Outcome
What does success look like?
See: #2544 (closed)