Knowledge Base

The knowledge base (KB) is a repository of solutions to commonly-encountered problems, created and maintained by support engineers. In the KB, we turn the knowledge created when we solve a ticket for one customer into a public resource that helps others self-serve – leveraging one-time effort into an article that can be used multiple times independently from the ticket assignee.

Principles

• Turn it into a habit. Write it down into the KB every time we solve a problem for customers, for a team member or for ourselves. The more we do it, the easier it becomes.
• Accelerate knowledge capture. Our tools and processes should enhance the speed at which we add knowledge to the KB, prioritizing capturing the right knowledge instead of capturing knowledge right.
• Dogfood and update as we reuse. The KB is as much for us as for our users. We review and update knowledge as we use and reuse it. If it isn’t used, don’t worry about it.

How KB differs from the docs

The knowledge base and our product documentation are both key elements of GitLab’s digital support experience that serve different needs:

You can use this as a guide when deciding if you should contribute something to the KB or if you should make it a docs update.

Implementation

We use Zendesk Guide to publish knowledge base articles and suggest them to users who are seeking help.

A list of knowledge base articles can be found at:

• Global support knowledge base
• US Government support knowledge base

Knowledge base articles are suggested when a user is submitting a ticket:

We use the Support Pages project to manage knowledge base content. This has the following benefits:

• The project is open to public, allowing everyone to contribute.
• Avoid vendor lock-in of our knowledge base content.

How to contribute

Submitting a KB article

1. Pick the appropriate template in the /kb-documentation/templates directory:
   • break-fix.md: Specific issues encountered by users with one or more specific resolution steps.
   • ‘how-to.md’: Specific steps to do a specific task. Does not need to be an issue.
   • question-answer.md: Simple article answering a question.
2. Duplicate the template, placing the new file in the appropriate directory:
   • /knowledge-base/all_instances: This is where the majority of knowledge base articles will live.
   • /knowledge-base/global_only: Typically for content specific to GitLab.com.
   • /knowledge-base/us_government_only: For content specific to our US Government product offerings.
3. Fill out the template with the content you’d like to contribute. Focus more on the technical content, while following the style and content guide as closely as you can.
4. Create the merge request using the Knowledge Base Article template.
5. Assign reviewers:
   • If timeliness is important, assign a Staff Support Engineer or Support Manager for review.
   • Otherwise, the template will assign the KB editors: currently @irisb or @weimeng-gtlb.

Reviewing a KB article

• Always. Be. Merging. Make suggestions and apply them yourself.
• It’s more important to capture the knowledge than to capture it with the right style and formatting.

Publishing a KB article

Publishing a KB article should be done by the person who merges a KB MR. After the KB article is merged:

1. Submit a request using the Support Super Form, selecting Create a Zendesk article for the field “What is this request concerning?”.
2. After successful submission, the Support Super Form will create an issue and post URLs to the published KB article. The sync may take 5 to 10 minutes to complete.

Roles

Contributors

Everyone can contribute. The most important thing is to capture the knowledge you’ve created while solving a problem. You don’t need any special training to begin.

Rapid reviewers

Staff Support Engineers and Support Managers are KB rapid reviewers who can be called on to approve and merge content without needing to wait for an editor to become available.

Rapid reviewers should:

• Be called upon when there is advantage to publishing changes quickly, i.e. when new product issues are encountered by users or as part of incident response.
• Collaborate with KB contributors on the technical accuracy of the content, prioritizing having updates published as soon as possible.
• Tag a KB editor after approving and merging a KB article merge request to ask for a style and format review and edit.

Editors

KB editors help ensure KB articles are accessible to readers and have consistent style and formatting.

To become a KB editor:

• Contribute KB articles.
• Talk to Wei-Meng Lee .

The current KB editors are:

• Iris Blackburn
• Wei-Meng Lee

View page source - Edit this page - please contribute.