FY24Q1 TW OKR: Improve contributor experience by streamlining and consolidating guidelines => 79%
Documentation to help contributors is available on at least these three primary sites:
- https://about.gitlab.com/community/contribute/
- https://docs.gitlab.com/ee/development/
- https://developer.gitlab.com/
This OKR is intended to:
- Ensure new contributors have a quick and easy experience
- Give contributors a single source of truth when looking for help
To do on docs.gitlab.com (7 items)
-
Edit Contribute to the development of GitLab and ensure the links are precise, not duplicated, and point new contributors to about.gitlab.com. -
Edit Contribute to GitLab and ensure the links are precise, not duplicated, and point new contributors to about.gitlab.com. -
Ensure the list of links on the Feature development page are not duplicates, and make sense. -
Come up with a standard name for the pages in the Development style guide section. Page title: Either <Feature> style guide
or<Feature> development guidelines
. Nav title:<Feature> style guide
or<Feature> guidelines
. Turns out these pages are not all actually related, and they will be moving in this MR, so the naming won't look completely consistent until that MR merges. -
Apply this standard on the pages in that section. gitlab-docs!3618 (merged) gitlab!113629 (merged) -
Come up with a standard name for the pages in the Feature development section. Page title: Either <Feature> style guide
or<Feature> development guidelines
. Nav title:<Feature> style guide
or<Feature> guidelines
. -
Apply this standard on the pages in that section.
(Note to self, if time, also edit doc/development/code_review.md
)
To do on about.gitlab.com (7 items)
-
Create a "First contribution" tutorial on about.gitlab.com. (Or possibly on docs.gitlab.com...)
For each page on about.gitlab.com, ensure it's a subset of the information on docs.gitlab.com and that it links properly.
Extra work we did
We ended up pulling in some other work, because there is just so much that needs to be done with these docs.
- A huge project to reorganize the nav for the Contribute to GitLab section. This will help both contributors and GitLab team members. (Preview here.)
- Moved Labels info from the Issues workflow page and put it into its own page.
- Updated all the handbook pages that point to the labels info, and added some missing info to the Labels page. There are still inconsistencies between the handbook and the docs, but there are now fewer.
- Worked on the Merge request workflow page, which has a lot of contribution information. As of March 5, we are still working on this.
Brainstorming
-
Survey all the sites for duplication and determine where the source should be.
- The "about" site lacks both a left and right nav. The lack of navigation makes it very difficult for this page to be the SSoT.
- The docs.gitlab.com site has too much other information that can be confused with the contributor information.
- The developer.gitlab.com site is an open field but has no maintenance plan if we were to create a new site.
-
Come up with workflow for first time user and review current experience. Maybe do quick usability test to show how bad it is now.
-
Make beautiful first time tutorials. (By repurposing or combining existing content as possible.) These tutorials should have an achievable goal so customers can experience success.
-
De-duplicate the mess, including possibly some of the following:
-
Fix some of the high level pages on docs.gitlab.com.
-
Fix some of the most important pages on docs.gitlab.com.
- For example, our default merge request template points people to an Acceptance checklist. And that page has a huge topic about the responsibility of the MR author...
-
Remove duplicate content from developer.gitlab.com.