Knowledge Article Docs versus Knowledge Articles
This section is provided to help guide you through the Knowledge article review process
Knowledge articles vs Documentation at GitLab
Understanding when to create a knowledge article versus updating documentation can be tricky sometimes! Our goal is to help you understand the difference between Docs and Knowledge articles, and how they differ, but also how they can work together. Use your best judgement!
Knowledge Articles are for problem solving and troubleshooting! These are for specific issues that our customers have. Knowledge articles are reactive, created from support tickets that provide immediate solutions to the customer issue. The audience is for customers that are having issues, support engineers that are resolving tickets and anyone searching for fixes to specific error messages or problems.
Documentation is for learning and implementing. Documentation helps users learn Gitlab features from the start. Docs are proactive, and strategic content that explains how things should work. The audience is more for new users learning GItLab, Administrators, developing features and some capabilities. Use Guidance.
Create a knowledge article when
-
Something works in most environments but fails in specific configurations
-
Involves third party integrations or tools
-
Version dependent
-
Has uniqueness to an issue
-
Can assist with troubleshooting (steps and diagnostics)
-
Temporary fixes available and you need to lets customers know
-
Have alternative methods for customers to try
-
Recovery procedures from error states
-
Quick fixes (they may be workarounds that have proven to work)
-
Have multiple causes for the same symptom
-
Migration or Upgrade specific information
-
Known issues
Example GitLab Knowledge Articles: “Pipeline fails with ‘Docker daemon not running’ error in GitLab 15.x with Docker-in-Docker”
“Resolving 502 errors when pushing large files to GitLab with HAProxy”
“Workaround for Runner registration failing with certificate errors on self-signed installations”
“Fixing broken MR diffs after restoring from backup”
Update or Create Documentation when
-
How features are designed to work
-
Best Practices , Recommendations
-
Standard implementation
-
Step by Step implementation guides
-
Compliance and Security information
-
Architecture decisions
-
Capability descriptions
Example GitLab Documentation: “Configuring GitLab Runner with Docker executor”
“GitLab CI/CD pipeline configuration reference”
“Setting up SAML SSO for GitLab”
“GitLab backup and restore procedures”
When in doubt:
Start with a knowledge article for immediate customer issues. Even if its a “Draft” article only, capture it! Capture it in the customer Context. It can always be reviewed. Promote to documentation if it becomes standard guidance Link between both resources! If you create a knowledge article, link it to the doc for further reference. The 2 work hand in hand! Iterate as understanding evolves. Knowledge is always evolving and updating.
40af7b6d)
