Below is a list of potential candidates for this milestone based on existing issues. It is not expected to burn down all of these and the UX Paper Cuts team is not limited to this list. If you have suggestions for us please add a comment linking to an issue.
I did some mockup designs and put them here: &3192 (comment 1776529943). Two of the community members asked questions and gave positive feedback on the design. I would appreciate if as a part of this initiative, we can get feedback from the UX Paper Cuts team on those designs and also help with UX review of delivering that feature.
Hello Plan:Knowledge team! We're targeting 17.1 to make some UX Paper Cuts updates to the Wiki we've linked to some initial items. Please also feel free to add other issues you may have that fall into the Paper Cuts bucket and we'd be happy to review.
Two asks:
Please take a look at this milestone and let us know your thoughts about the issues identified and if you have others in mind
Our new process states that by default we add a UX designer and an Engineer as reviewer from the affected group (instead of using Roulette) on all MRs. However this can get noisy and some Groups opt out. What is your preference? And if you'd like someone from your Group, who'd be best?
We do not have an assigned UX designer, so I would either consult with @dteverovsky for review or @himkp who has been leading our engineering efforts in the Wiki.
@paintedbicycle-gitlab yes, the UX Paper Cuts team can send any frontend reviews to me. I understand most of the backend logic in Wikis too, so I can help out if needed, but I'm not a maintainer. When the MRs are ready, I can help pick backend reviewers and maintainers who have worked on Wikis in the past, depending on whether they have capacity for reviews or not. If not, we can go by the roulette.
Exciting to see Wiki being a focus @paintedbicycle-gitlab ! If @mmacfarlane , @himkp or I have proposed papercuts should we leave them as comments in this issue?
@mushakov Absolutely! We would love that. Our new process is that we reach out to the affected Groups a few weeks in advance to give them a chance to do exactly that, to read through the issues we've identified giving you time to let us know if you have any concerns or if you or others want to be consulted on the solutions for any of the larger ones. We can't guarantee that we'll have time to fix any specific issue, but please do send them our way and the team will take a look.
@mmacfarlane It would be a nice-to-have to do a UX scorecard done ahead of this milestone to identify usability issues. Typically, this would be done by a UX designer, so we'd need to get creative on that front.
@paintedbicycle-gitlab, I'm not sure if you or @clavimoniere have interest and bandwidth to conduct any scorecards, but if so, that would be one option. Another option is for me to do one. Or, some combination.
@dteverovsky I'm not certain it's feasible given we have 12 business days left in this Milestone (as of 2024-04-24). I also haven't completed a UX scorecard prior, so maybe I'm way off base and this is an exercise that would only take a few hours or days. I'm open to doing it if I have some support!
@mmacfarlane It can be a pretty lightweight exercise, especially if we do Option A: heuristic eval (~ half a day). Or, we can do Option B with internal users - consider it lightweight usability testing (~1 day, depending on the scenarios we choose to test).
Define the JTBD that we want to test (i.e., top 1 or 2 jobs related to Wiki usage).
Draft a scenario to test doing that job in Gitlab.
To save time, I suspect we can do this work in our GitLab instances, rather than creating a test environment
Then, we would test - either do an expert evaluation using pre-defined heuristics, and map out the flow in a journey map. Or, test with 3-5 internal users.
We have a sync session Wednesday May 8th at 11ET if anyone with strong opinions on wiki improvements would like to attend. So far it's @mmacfarlane and the UX Paper Cuts team
“Edit sidebar” should not open a “new page” overview. Confusing to be brought out of context.
And, confusing on how to edit, not just create a new list of items.
Mismatch between what I'm trying to edit, and the editing view I see "New page"
Drag and drop sidebar pages to reorder and re-nest?
What happens if someone edits the sidebar, and they want to access a page that is no longer listed in the sidebar?
Creating a new nested page should be more clear, not just append the title with the home/ path
Confusing on what the actual title will be vs the location of the page
“Clone repository” —> “Clone wiki” or "Clone wiki to new location"?
Also, unsure if wiki should be capitalized or not...
Wiki users may not be comfortable with "repository", and I'd argue they don't need to be to fully use the Wiki and its version control that is built in via being a repository. Essentially, an opportunity to layer easier UX over the actual mechanism, while explaining the mechanism in Docs (or something).
Not enough feedback on crafting the page hierarchy
The plus buttons in the sidebar sort of work as expected, but sort of not.
I saw an issue about enabling an empty page to be created --> it would be interesting to be able to create a bunch of empty pages within the sidebar.
Table editing improvements
Drag and drop rows
Better copy/paste of row contents to other rows
Editing the page itself - the description edit view.
Resize edit view to larger and wider? A wiki page may be more extensive than a typical issue, epic, MR, or comment. In general, that resize would be nice while editing.
Linking and moving pages
Linking to pages
The following is confusing - I understand what a path is, but without an example, or more guided UI selections, this is hard. It's relying on recall over recognition for the names of pages and locations:
Tip: You can move this page by adding the path to the beginning of the title. Learn more
Questions that could be made more apparent in the Wiki:
Can I text search just this wiki?
If my project doesn’t already have a wiki, how do I create one? Discover one?
Personally, I get confused between "slug" and "path" terminology...
@dteverovsky Thanks for the insight. I can provide some more context on why certain behaviours you mentioned are this way.
Sidebar
Wiki sidebar was an inherited feature of Gollum. When we first introduced Wiki, we used Gollum to make it easier to render wikis in GitLab. However as our product matured, we brought in our own custom markdown parser (Banzai pipeline) and other features and deprecated many features of Gollum. As of today, we don't use Gollum at all, but some of the behaviour we inherited from it still remains.
In Gollum, the sidebar is just another markdown document named _sidebar.md. We mimicked that functionality in GitLab in preparation to remove Gollum. So when you edit the sidebar, you just create or edit a page called _sidebar.md.
Drag and drop sidebar pages to reorder and re-nest?
We can create a sidebar editor that lists all the pages and helps you organize. Perhaps would be helpful to rethink the design and functionality of the sidebar.
What happens if someone edits the sidebar, and they want to access a page that is no longer listed in the sidebar?
They either need to delete the custom sidebar to access the actual sidebar, or go to the list of all pages manually project/path/-/wiki/pages to find the page.
not just append the title with the home/ path
Currently the sidebar has the functionality of creating a page in a directory using the + icon. But it is severely limited since the sidebar can only render 15 pages at max.
Clone repository
It allows you to clone the wiki repository to your local system using git. Perhaps we should have a code dropdown here just like in a project.
We are also considering deprecating access to the wiki repository since to add support for per page user permissions, the wiki repository read access needs to be limited to admins only.
Table editing improvements
For this one feel free to open the issue directly with labels Category:Rich Text Editor and groupknowledge. This relates to the rich text editor and applies everywhere rich text is used, not just the wikis.
Linking and moving pages
We have a [[ autocomplete shortcut to link to wiki pages. See demo: https://www.youtube.com/watch?v=qqN6KxMB06E. As for moving pages, I am working on a redirection system this milestone to make sure any renamed pages still work with the old URL and are redirected properly: !150727 (merged)
Small bug here: The hexadecimal UUID should not be prefilled the title. This can be avoided by passing ?random_title=true in the parameters, but it seems that it is not passed when creating a template when no wiki page exists.
Improve visual hierarchy of sub-pages. This is a terrible example, but Level 1.1, Level 1, and z are all at the same hierarchy, but items that have sub-pages have different indentation:
Level 3 is a sub-page of Level 2 but it has the same indentation
IMO: I like the nesting ability, but have no idea how widely it's used. Without folders it's quite hard do manage big wiki's and nesting pages seems natural to me.
@vshushlin That makes sense. From looking at the examples @himkp linked to, I don't see any with more than 2 levels of nesting (and just to verify, we have no way of seeing if there are any wikis with more than 2?) and I was hoping to avoid the following situation
I believe we cap the epic tree at 5 descendants; wondering if that makes sense here too?
@annabeldunstone We can definitely restrict showing upto 2-3 levels of pages in the sidebar, but since wiki pages exist in a repository, there is no theoretical limit to the amount of nesting.
There are many such issues with the sidebar. For example, the sidebar should not just show 15 items. It can have a virtual scroll for a large list of pages, or the folders can stay collapsed by default, and we load the list of items in the folder only when expanded.
All of this requires the sidebar to be migrated to Vue first. I created #461806 (closed) and listed the possible features we can add once we do that.