Improve docs experience for Experience Baseline JTBD: Create a Merge Request
As part of the FY20-Q3 documentation OKR &1678 (closed), this issue pertains to a "job to be done" (JTBD) in GitLab--"Create a Merge Request"--which has been evaluated by UX as part of an Experience Baseline Review.
If you are working on this issue, review the linked OKR and the Experience Baseline Recommendations Handbook page for more detail. Then review the links below, per the OKR instructions.
UX Evaluation issue - gitlab-design#441 (closed)
UX Evaluation video - https://www.youtube.com/watch?v=WOdqw_z2dwE
UX recommendations issue - gitlab-design#444 (closed)
Potential doc work - Link from UI to MR Approvals doc page; Ensure the steps of the MR process are sufficiently documented
Technical writer - @marcel.amirault
Product designer - @mvanremmerden
Based on the steps in the OKR epic, use the checkboxes to indicate when each step is complete, and use the format below for notes and plans. You are welcome to alternatively link any/all subsections to an additional issue or a Google doc, to work there instead.
-
Review existing info -
Review SEO -
Document and improve SEO
-
-
Consider potential UI doc link -
Review and improve documentation content -
Test the instructions -
Plan documentation improvements/additions -
Ask questions of and share plans with Product Designer -
Implement doc changes
-
Plans & Notes
1. Review existing info
The merge request UI can be interpreted in different ways, as shown in the evaluation video, and there is a lot of unexpected behavior. There is also a huge amount of functionality for a single page (all New Merge Request features, like description and checkboxes, and the right side bar after the MR is created).
2. Review SEO
Poor experience. Searching for exact term almost always ends up with the wrong page listed at the top and you have to scroll down and try to find the page you want. The search engine itself needs to be improved.
a. Document and improve SEO
Likely not possible to improve the searching experience until the search system itself is improved.
As a result, I'm adding new entries to the global documentation navbar for two JTBD: Creating a merge request
and Reviewing and Managing merge requests
, which should improve the ability to find these docs without using the search feature:
3. Consider potential UI doc link
Options explained in: #31708 (comment 238128759)
4. Review and improve documentation content
- The merge request documentation (https://docs.gitlab.com/ee/user/project/merge_requests/) is huge and spread over many pages.
- The largest page is the
index.md
which is massive, but things don't seem to be listed in any particular order.
- The largest page is the
- The new left-nav for the docs site helps, especially if you are looking for a topic listed in the nav bar. If it's not listed there, it may be unclear that it's in the top MR index page.
a. Test the instructions
Instructions were all valid, but poorly located and hard to find.
b. Plan documentation improvements/additions
Brainstorming:
- Try to find more "related" topics, create those topic pages and bring MR content there, and reduce the size of the index?
- Use index as a simple landing page, to direct to correct doc?
- Order MR instructions based on where they are found in the MR page? Based on the right bar? Based on topic only?
- Create a basic "creating a merge request" page, like gitlab-basics, with the basics, and a separate detailed/advanced page to gather more of the advanced features that don't fit into their own page?
- Mermaid diagram of a merge request workflow linking to docs
Notes:
- It may be possible to split merge request documentation by the type of user:
- A basic developer needs to know how to create and update merge requests, and will work with the MR based on how the instance is configured.
- An instance administrator/maintainer may need to configure the merge request features that the developer will use, and perhaps these can be isolated in their own area of the documentation?
Final Solution:
Split merge request index into three pages:
- index.md: Act as an index only, with use cases. Use to quickly find correct docs. Simplify structure significantly, and have a useful TOC.
- creating_merge_requests.md: Explain workflow, give easy to understand intros, collect all features that used to be in index, but relate to creating MRs. Have all options from the "Create a new merge request" page listed at the top, so anyone "stuck" while creating an MR can find the information needed quickly.
- reviewing_and_managing_merge_requests.md: Collect all features that used to be in the index, but relate to reviewing/managing MRs. Follow-up work: Need to add more workflow information, better intros.
c. Ask questions of and share plans with Product Designer
I kept Pedro and Marcel up to date in this issue and in the MR, as my work progressed.
d. Implement doc changes
Improvements to the entirety of the merge requests documentation done in !18644 (merged), which should improve the experience overall. Specifically, the JTBD of Creating a merge request
now has a specific page in the documentation which could be linked to by the UI, if desired. If not, it should still improve the experience if a user goes to the docs for trouble with creating a merge request:
Significantly simpler Merge Request documentation, which also improves a secondary JTBD (Reviewing a Merge Request
):
- https://docs.gitlab.com/ee/user/project/merge_requests/index.html
- https://docs.gitlab.com/ee/user/project/merge_requests/reviewing_and_managing_merge_requests.html
The second page should be expanded with more information about common workflows and a better introduction (not done in the linked MR as it was out of scope for this issue, but should be done as a follow-up).