Global Knowledge Base

The Global Knowledge Base is a searchable repository of Solutions to customer problems, designed to help users quickly find answers to their questions without having to contact support.

Knowledge base articles can be found here

• Global support knowledge base
• US Government support knowledge base

Benefits:

• Deflects ticket creation.
• Resolves user problems faster.
• Creates consistent, standard answers.
• Creates an environment of trust.
• Gives Support more time to focus on harder issues or improvements.

Principles

• Turn it into a habit. If the issue is worth solving, it is worth saving.

  • Start a knowledge article every time you solve a problem for a customer, a team member or yourself.

• Accelerate knowledge capture. Our tools and processes should enhance the speed at which we add knowledge to the Knowledge Base.

  • Capture Knowledge in the moment when the context is clearest and we are able to access customer feedback.
  • Provide feedback as soon as possible if you find a better way to do something.

• Capture customer context. Prioritize capturing the right knowledge, in the context of the customer.

  • Focus on documenting the errors and issue as described by the customer for improved findability from other users.
  • Include clear steps and context when documenting solutions. When in doubt, ask, would Josh Darnit be able to do it?

• Always be iterating. The Knowledge Base is as much for us as for our customers. We review and update knowledge as we use and reuse it.

  • Reuse is Review: We improve the quality of our knowledge by always iterating.

How Knowledge Articles differ from GitLab docs

The Knowledge Base and our product documentation are both key elements of GitLab’s digital support experience that serve different needs. See examples and learn more here

Docs

Docs answer: “How does this work?”

• Offers comprehensive information about Product features, architecture and Usage.
• Provides an overview of the current version of our products.
• Often more technical and detailed
• Updated less frequently (New Feature releases)
• Primarily created for engineers, advanced users, Product details

Knowledge Articles

Knowledge Articles answer: “How do I fix this?”

• Solves problems encountered while using our products.
• provides solutions to common issues and questions
• typically task oriented and includes videos, screenshots
• Updated frequently based on new issues, new workarounds, new troubleshooting and feedback
• Primarily created for customer self-service

Why you should create a knowledge article

Knowledge articles help users to do tasks, get answers to questions and fix issues they may encounter while using our products.

Did you know that Knowledge can be INTERNAL or EXTERNAL?! Knowledge articles arent just for Customers. They are for Internal users as well. Within a knowledge base we offer internal only knowledge that assists our internal team members.

We use types of knowledge to efficiently provide the information for our end users. This includes:

• How-To
• Break/Fix
• FAQ (Question and answer)
• Troubleshooting
• Process

When to create a knowledge article

In short, you should create an article when someone will benefit from the information.

Some questions to consider:

• Will it help customers find information quickly?
• Does it answer a common question / issue?
• Does it document a repeatable way to do something?
• Would this information help a customer get what they need without Support intervention?
• Is this information that may need frequent updates?
• Is this a new issue (with or without a solution) that may cause an influx of support tickets?

What can be / should be part of a Knowledge Article?

• Overview
• Workarounds, Root Cause, Issue
• Videos (Link to video)
• Screenshots (Be careful to not add screenshots of Personal Identifiable information)
• References (be careful of internal links if the article is external)

What Training is Available for Knowledge Articles in ZenDesk?

A list of available training can be found in Knowledge Base Training Resources.

Implementation

Starting February 2, 2025 we will use a Sync Repo to create, modify, and publish knowledge base articles.

Want to see how to create a knowledge article in the Sync repo? Check out our LevelUp video

Here’s what you need to know

• We are still aligned with Zendesk. THe sync repo will ‘sync’ knowledge articles iwth Zendesk to present to customers.
• The Create article button in Zendesk will still be present, however it will direct you to the sync repo (a note will be displayed).
• The knowledge articles will still be present on the knowledge base of our Support Portal.
• Support Engineers will still be able to link knowledge articles and/or documentation to a support ticket by using the search feature.

What’s NOT changing

• Zendesk remains our tool for support tickets

• Customers see no difference

• Internal article visibility stays the same (look for the 🔒 icon for internal-only content)

• How you view articles is unchanged

• TL;DR: Same reading experience, new writing process.

How to create a knowledge article in the Sync Repo

The following process is creating a knowledge article using a WebIDE and Knowledge article temmplate. A video has been created to Guide you as a visual.

1. Go to the Sync Repo Project Articles
2. Open a WebIDE (use the period on your keyboard to open the WebIDE)
3. Drop down the arrow next to the Knowledge Articles (Right side) and choose the Templates folder.
4. Drop the arrow next to the Templates folder and choose one (Breakfix, FAQ, How-To, Process).
5. COPY the entire File Information
6. Go to one of the SECTIONS under Knowledge Articles (Administrative, CI_CD Pipeline, Errors, how To, Kubernetes, Licensing and subscription, Migrations, Other articles, performance, Security, Upgrades, Troubleshooting) . If you do not see a section that needs to be added we have a way to do that! See the Section details here: https://handbook.gitlab.com/handbook/security/customer-support-operations/zendesk/knowledge-center/sections/#current-sections-in-use
7. Right Click on the Name and choose “FILE”
8. Name the File (Your Article Title) and add .md after the title: Example - TitleOfYourKnowledgeArticle.md
9. Paste the template details you copied into the right side panel.
10. Enter the body (details) of the knowledge articles (remove or add information as needed).
11. Save, Commit and Create the Merge Request (MR)

Update the Top Metadata Fields FIRST:

• Title: Change the TITLE (to the title of your knowledge article)
• Previous Title (should match the Title)
• Category- Knowledge Articles (Leave as is)
• Section - Add the section that the article should be in (Administrative, CI/CD Pipeline, Errors, How To, Kubernetes, Licensing and Subscription, Migrations, Other articles, Performance, Security, Upgrades, Troubleshooting).
• Author (will be you)
• Tags - add as needed
• Labels - Add as needed
• Instances - the article will be shown in both Global and Gov knowledgebase. If the article is to only go to Gov, remove the Global. If hte article is to only go to Global remove the Gov line.
• Public - is set to TRUE. This indicates the article is PUBLIC VISIBLE. If the article is to be INTERNAL ONLY set to FALSE.
• Convert_markdown - True - this is set to convert your article body from markdown to Zendesk language. only set to false if you want a “raw” dump of your article body. into a Zendesk article.

Note: The Workflow will then be started - MR Created, Approvers will validate (review), article will be approved and added to the Sync Repo and then visible on our Knowledge base.

Other ways to Create Knowledge Articles

Option 1- External Template Request

1. Go to the Folder and choose a template
2. Create the article using the template and Save the document.
3. Use the Knowledge Slack Channel #spt_knowledge-base to request the article to be created. Please tag Kirsty Allen .
4. Your Article will be created in the sync repo and assigned to a Reviewer & then Published.
5. Roels and Permissions remain. The same “Reviweers” today will have access to Approve an MR to publish an article.

Option 2.-Template Support Team Meta

1. Use the template under Support Team Meta . The Template is named knowledge-base-article-request. Make sure to tag Kirsty Allen
2. Your Article will be created in the synnc repo and assigned to a Reviewer & then Published. You will be notified of Publication.

Option 3-Create through Slack

To create a NEW issue to Knowledge use the following Command in Slack

• /gitlab gitlab-com/support/articles issue new

To UPDATE an existing issue in Slack, use this command in Slack

• /gitlab gitlab-com/support/articles issue comment Work item number (shift + Enter) Add the comment

Roles and Permissions

There are three roles: Support Engineer, Knowledge Champions and Knowledge Admins.

• Knowledge Contributors: Create, update and use KB articles in tickets.
• Technical Reviewers: Will review an article for technical accuracy before its published.
• Knowledge Champions (Coaches): Create, Modify, Review, publish, as well as Mentor Junior Members (knowledge), identify opportunities for knowledge.
• Knowledge Admins: Ensure processes are followed, assist with archive, restore.

Please see the Knowledge Roles Permissions, and Responsibilities page for more information.

Knowledge Contributors

Everyone can contribute to knowledge! The most important thing is to capture the knowledge you’ve created while solving a problem. The review process will ensure the content is technically accurate and clear.

Technical Reviewers

There will be Support Engineers and Support Managers trained as technical reviewers for knowledge articles across the globe.

Technical Reviewers can be found under Column 4 (Looking to Help others) on the Skills by Subject Page Technical Reviewers should be Subject Matter Experts (SMEs) in certain areas (Such as Runner, Authentication, Migrations, etc.). The Technical Reviewers are tasked with reviewing knowledge articles based on their knowledge of features.

Technical Reviewer Responsibilities

Technical Reviewers are expected to:

• Prioritize and Normalize Reviewing articles
• Collaborate with Knowledge article contributors on the technical accuracy of the content, prioritizing having updates published as soon as possible.
• Technically review knowledge articles and determines if the article can be Published for customers (or should remain internal).
• Understands the material and requirements for the article being published.
• Identify trends and opportunities from reporting.
• Provides feedback for knowledge articles.

Knowledge Champion

A knowledge champion is someone who will advocate for knowledge, promote KCS and knowledge articles, as well as assist with driving knowledge management for the product/features. The knowledge champion will help bridge the gap between knowledge and support engineers.

Knowledge Champions will:

• Help Mentor Junior Support team members around knowledge
• Find areas where we have opportunities for knowledge, gaps, risks.
• Assist with the knowledge Review Process
• Assist with Technical Reviews when needed
• Attend Once a Month Team KM meeting (to discuss issues/information)

Getting Help

Questions can be asked in the dedicated #spt_knowledge-base Slack channel.

For any issues with permissions, please use the knowledge dedicated Slack channel: #spt_knowledge-base - and tag or open an Issue and tag Kirsty Allen .

Linking knowledge and other Content to Support Tickets

Are you Linking Content to a Support Ticket?

Did you know that it can be a document, an issue or a knowledge article? Linking ‘any’ knowledge to a support ticket creates a critical feedback loop for us. It provides valuable insights into opportunities, as well as measurements. We have not yet made it a mandatory process yet. HOWEVER, We need and want this to become the norm’ for you during your support workflow. Try it!

How can YOU help?

We have the capability to Link knowledge throughout the lifecycle of the ticket (not just at Resolution), however, we should make sure we link before resolving the ticket completely. Note: Not EVER ticket will require a link. Do not just link for the sake of linking. Link knowledge when it adds value, not just to check a box. It should be helpful!

How do I link

• Use the Knowledge Capture app (on the right side when you are in a support ticket)
• Use the Search- to search for an article or a document.
• You can view the article in the ticket view or you can view it on the page view.
• Use the link icon to link the article or document to the Support Ticket.

When to Link:

• When an article, document or issue is used to Solve the problem
• It Benefits the customer
• It helped in your research for the support ticket
• Provides knowledge for you and the customer

When NOT to Link:

• The article doesn’t cover anything with the support ticket (doesn’t help)
• The article wasn’t really used to help support the issue
• Is being used to just to close (doesn’t match the issue of the ticket)

Link content when there’s real value in the connection. The goal is to build intelligence around support tickets (What documentation helps, Where gaps exist, what could have been deflected).

View page source - Edit this page - please contribute.