**_Update coming in April 2025, see the new DRAFT Documentation Roadmap:_** https://gitlab.com/groups/gitlab-org/-/epics/17363 The GitLab documentation site assists all users of all GitLab tiers. In 2024, the percentage of docs site visitors who were **new to GitLab** (1 year or less) **was 49%**. The current Technical Writing focus is to help new users ramp up. The percentage of daily users of the docs site (18%) is continuing to grow. The documentation roadmap is an ongoing plan to fix identified problems with the documentation content, the [docs.gitlab.com](docs.gitlab.com) platform, and /help. We update the roadmap as we learn about the ongoing needs of docs site users and as we complete projects and initiatives. We learn about how people use the documentation from the research listed in the **Identifying Problems** section below, as well as verbatims from the [Paid Net Promoter Score](https://about.gitlab.com/handbook/product/product-operations/surveys/) and from the quarterly [System Usability Scale](https://about.gitlab.com/handbook/product/ux/performance-indicators/system-usability-scale/). ## Themes Discovered in Research * 35% of docs site visitors - more than a third - are there for the first time. This percentage has more than doubled in two years. * The percentage of **new GitLab users** (1 year or less experience with GitLab) who visit the docs site remains high. Approaching half of all respondents (49%) have used GitLab for less than a year. * In general, it has been **hard for people to find the information they’re looking for**. The docs site, [already large](https://handbook.gitlab.com/handbook/product/ux/technical-writing/#docs-site-stats), continues to grow monthly. * While our surveys in the past showed that the success rate for finding content was getting worse, the 2023 survey showed that the trend downward has stopped. We hypothesized that the new Google search would improve findability, and it seems to be true. As for the amount of content on the site, one self-managed GitLab user says: “GitLab has far more functionality than our team will ever use. Just the ... size of documentation makes finding any one thing harder,” and this comment is still true. * Some **basic information that people want is missing.** A common user request is a tutorial or video to get started in a particular area of the product. * Users want more contextual **_why_** information. * The differences between GitLab versions, the features in free vs paid, and the features available in self-managed vs SaaS vs Dedicated are not always clear. ## Solving Problems in Related Epics/Issues | Priority | Epic | Description | |----------|------|-------------| | 1 | [Docs site replatforming](https://gitlab.com/groups/gitlab-org/-/epics/11891) | The docs site platform needs modernizing. [Beta is available](https://new.docs.gitlab.com/). [See the research in this completed KR.](https://gitlab.com/gitlab-org/technical-writing/-/issues/849) | | 2 | [Revamp of /help and docs.gitlab.com](https://gitlab.com/groups/gitlab-org/-/epics/7738) | The differences between /help and docs.gitlab.com confuse users at a time when they're looking for assistance. Making the experiences consistent and making a version of docs.gitlab.com available for air-gapped customers will help solve this problem. | | 2 | Expand the Developer Portal | https://gitlab.com/gitlab-org/gitlab/-/issues/329648, https://gitlab.com/gitlab-org/technical-writing/-/issues/561, https://gitlab.com/gitlab-org/gitlab/-/issues/299428 | | 3 | [Troubleshooting Docs](https://gitlab.com/groups/gitlab-org/-/epics/4702) | To provide more extensive and findable troubleshooting docs, this epic helps us understand the current content and process, provides a level of competitor research, and through analysis, provides recommendations for improvements. | | TBD | Content variables ("keyrefs") for write once, use many | | Work is ongoing, and several completed projects are listed below. ## Completed | Priority | Epic | Description | |----------|------|-------------| | Complete! | Define needed ["Getting Started" topics](https://docs.gitlab.com/ee/development/documentation/topic_types/get_started.html) | During the [Anthropic Claude experiment](https://gitlab.com/gitlab-org/technical-writing/-/issues/974) and in [follow-up KRs](https://gitlab.com/gitlab-com/gitlab-OKRs/-/work_items/5774), [identify the missing cross-feature topics that address questions from a user perspective](https://gitlab.com/gitlab-org/technical-writing/-/issues/983). The topics are identified, with only two left to complete ([Analyzing GitLab usage](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/148270) and \[Managing users\]).(https://gitlab.com/gitlab-org/gitlab/-/merge_requests/147021). | | Complete! | [Home page refresh](https://gitlab.com/gitlab-org/technical-writing/-/issues/854/) | A quicker and more organized way to reach lower level pages on the docs site will help with findability. | | Complete! | [Improved Search](https://gitlab.com/groups/gitlab-org/-/epics/9420) | Google search is now live on [docs.gitlab.com](docs.gitlab.com), replacing Algolia. | | Complete! | [Tabbed content capabilities](https://gitlab.com/gitlab-org/gitlab-docs/-/issues/998) | Tabbed content ensures that readers can view version- or environment-specific content, hiding content they don't care about, and makes the documentation page less cluttered. [This capability](https://gitlab.com/gitlab-org/gitlab-docs/-/merge_requests/2904) will help with versioning improvements. | | Complete! | [Context-sensitive documentation](https://gitlab.com/groups/gitlab-org/-/epics/6532) | docs.gitlab.com is separate from the GitLab product. Some product pages include links into the documentation. Most pages do not. Being able to access page-specific documentation would help users more quickly than using Google search to find what they need. The ability, patterns, and guidelines to [provide Help information in a drawer component](https://design.gitlab.com/usability/helping-users/#providing-reference-information) are now available. | | Complete! | [Recommend next steps for Disqus](https://gitlab.com/groups/gitlab-org/-/epics/6670) | Disqus is a user-commenting tool inconsistently posted on the docs site. The Technical Writing team does not currently monitor these comments. The linked epic is a research spike. | | Complete! | [End-to-end tutorials](https://gitlab.com/gitlab-org/technical-writing/-/issues/506) | Current GitLab documentation is feature-based. People don't come to GitLab to use features; they come to set up and use CI/CD, to manage source code, to collaborate and build software. The documentation does not provide these higher-level tasks. The doc, to its detriment, reflects the development environment and process. The linked OKR is an MVC solution. | | Complete! | [Define content design](https://gitlab.com/groups/gitlab-org/-/epics/4655) | Providing a defined documentation content strategy will improve topic organization and improve site findability and usability. | | Complete! | [Visual design: Docs site Beautification](https://gitlab.com/groups/gitlab-org/-/epics/4527) | Visual design improvements make the docs site less cluttered, more polished, and easier to scan. | | Complete! | [Left and right nav](https://gitlab.com/groups/gitlab-org/-/epics/4654) | Research showed users considered the docs site difficult to navigate. An improved and standard information architecture can help users find what they need more easily. | ## Identifying Problems The roadmap is informed by the following research: - [FY25 May CSAT and FY25Q2 SUS Verbatims about docs](https://docs.google.com/spreadsheets/d/1l9WbV0wLCn93cDq_Nif8Ox74w4XzsbK4fblDYyiKSkE/edit?gid=0#gid=0) - [State of the Docs Site 2023](https://docs.google.com/presentation/d/1VxQ1yDoMUYObB4-kowj1lRROVqDxfXNmd21YG16f2tc/edit?usp=sharing) (See the public video [State of the Docs Site 2023 Survey Report](https://www.youtube.com/watch?v=UsrxGegHxD4)) - [State of the Docs Site 2022](https://docs.google.com/presentation/d/1cwMUYPBWrDbqmqSHlQQ_geaPaYF26_GyANJlZ0DJKIM/edit?usp=sharing) (See the public video walkthrough [State of the Docs Site 2022 Survey Report](https://www.youtube.com/watch?v=5k6FTvm_2cU)) - [Docs site content audit](https://docs.google.com/spreadsheets/d/1nwlv19hJ6I2RpOngA0pbCdVupUvP5QqM4kTJ8OuI3kY/edit#gid=722849967): ongoing and updated regularly - [State of the Docs Site 2021: UX Research](https://docs.google.com/presentation/d/10pptprfhSur1cBrA8OYDRlzsnNg6RXiy5InCsVSOGyo/edit?usp=sharing), (see the public video [State of the GitLab Docs Site (2021): Research Findings](https://www.youtube.com/watch?v=pv4uvDemGos)) - [Learnability longitudinal study](https://docs.google.com/presentation/d/16hWaDGqkrIg2qQW-uJ7pIDWlwfyDwaXG3q9EXGlXZaI/edit#slide=id.gf2aa91fc46_0_210) - [Learnability interviews](https://docs.google.com/presentation/d/1bXUiRRwr50WhoOd0ko-eG-mm_0C6U8UjCR3PMqr7TZU/edit#slide=id.g469c9b8c47_0_0) - [Information architecture research and tree-testing](https://dovetailapp.com/projects/UvJCh1ZkTylHi1gseJB8j/readme) - [2020 research findings](https://docs.google.com/presentation/d/1h-rISbpsl1D73Or6dVJm6Do7gP7oXlAdURODMQ18GLg/edit#slide=i), including [stakeholder](https://dovetailapp.com/projects/3JbnI2GyCPccGPugJpgUBd/readme) and [user interviews](https://dovetailapp.com/projects/5uD255dxkJkTMte59w2e2B/insights) (or see the public video [State of the docs 2020 - GitLab UX research](https://www.youtube.com/watch?v=BQGEeHCBA58))