Q4FY2022 KR: Make it easier to find tutorials on docs.gitlab.com
According to UX research, learnability is an ongoing issue in GitLab. The documentation is organized by feature, not necessarily by How To topics, so we want to provide an MVC to help people ramp up.
We want to make it easier for GitLab users to find tutorial content in the documentation and elsewhere. Several teams provide information about learning GitLab, and we want to create a singe page where people can find that info.
The MVC for this KR is a Get started with GitLab
type of page on docs.gitlab.com that surfaces tutorial content from a number of sources:
We'll add to this list as we discover more potential sources.
What problem is this MVC trying to solve?
The docs page we create should answer: If somebody doesn’t understand how to use GitLab, where should they go to learn more?
What do we mean by "tutorials"?
From the documentation style guide:
A tutorial is an end-to-end walkthrough of a complex workflow or scenario. In general, you might consider using a tutorial when:
- The workflow requires a number of sequential steps where each step consists of sub-steps.
- The steps cover a variety of GitLab features or third-party tools.
The format of this content can be:
- Written tutorials in the documentation.
- Video tutorials.
- Other media, such as slides or training decks.
To avoid dumping too much content in our tutorial page, we'll apply the following criteria:
- The focus of the content should be about learning how to use GitLab. We won't include tutorials about configuring external tools, such as Docker. While these might be part of the overall GitLab flow, we should focus on core GitLab for this MVC.
- The content should provide a step-by-step walkthrough that can help achieve a specific outcome, or it should be a suitable learning aid (such as a cheat sheet). Resources that provide general overviews (such as a landing page about a feature) are not specific enough.
Challenges
- Pages of
Get started with GitLab
links are already in the docs today: - Our own style guide discourages the use of Topics and resources pages
We do not encourage the use of these types of pages. Lists like this can get out of date quickly and offer little value to users.
- Tutorial content should be easily accessible in the context of the feature and product area that they relate to. We have previously removed top level "Tutorial links" pages from GitLab docs based on this rationale.
Now that we know that learnability is an issue, we can leave tutorial content with its relevant feature, while listing it along with other helpful links on a Get started with GitLab
page.
Steps to the MVC for this KR
-
Confirm the primary personaaudience that this page is aimed at.- Our focus is on new users (new to GitLab, and new to parts of GitLab they haven't used before), not on a specific persona for this MVC. New users are especially affected by Learnability challenges. This is reflected in our SUS results and Learnability research.
-
Agree how much content is "enough" for MVC. This could include an early draft MR of how the content can be grouped and structured. -
Identify sources of tutorials that we could link to from the docs page. Include foundational work completed in gitlab#331618 (closed). Add to this, sources from GitLab Learn, Growth team initiatives, and TAM team initiatives. - The various sources of info are collated in this Google doc (ongoing, adding more info as we find it).
-
Decide whether to redesign an existing page, such as New to Git and Gitlab?, or create a new page. -
Create a draft of the page for review. Reviewers to include: @asmolinski2, @susantacker. -
Set up the page to be discoverable for MVC. This includes review with Suzanne Selhorn to agree left-nav and docs home page discoverability. -
Identify any potential gaps in the information already available.