containers
UX: Mockups for Search in Documentation
UX Description
Along with the description of the epic: https://github.com/podman-desktop/podman-desktop/issues/11180
We would like to create the mockups that are showing how the end users could search in the documentation. We would like to stay consistent with how the search is working on the website.
It will also be important to handle the case where the user is not able to reach the website service, because of connectivity or network policies
Deliverables:
- Wireframes for the search window and surrounding interface
- Low-fidelity prototypes of the search functionality
- Research on related design patterns and best practices for search UI
Request type
None
Primary Contact
No response
Deadline for request
No response
Starting Research here: https://miro.com/app/board/uXjVIJnYtgc=/?share_link_id=804410839476
I am putting my findings here: https://miro.com/app/board/uXjVIJnYtgc=/?moveToWidget=3458764623183099654&cot=14
I have created a number of frames in the Miro.
It goes over the user stories, other products examples and highlights some initial ideas. I suggest a few possibilities on how to access search functionality and will be happy to review them next week in a meeting.
Other products examples can be seen here.
I would also like to discuss a possibility of creating an AI Assistant / chatbot trained on Podman Desktop own documentation and using our technology.
Here's the 2 main options I'd like to discuss: miro frame.
As far as the functionality itself, I believe it could be the same search engine that is used on the site? https://www.algolia.com/developers
There's a couple more additions on the page, namely a description line under the page title with a learn more link:
Another one is changing the 'Search [containers]' text to say 'Filter [containers]"
In the UX call yesterday we briefly discussed the proposed options link to Miro
Some feedback:
- team responded positively to adding an (i) icon next to page titles to make it easy to access external documentation.
- if you press f1, a command palette appears. @axel7083 suggests the following:
VSCode has it, JetBrains tools has it, users are used to it. Like it as a popup, we could have several section including the documentation - we agreed it is somewhat confusing to have two searches within one page, so we discussed a possibility to rename the current 'search' to 'filter' (which it is) and changing the icon to something else.
-
we also discussed the placement of the search icon: whether it could go on the left nav or somewhere on the top. There were certain reservations in the team regarding adding an extra item on the left. Options 1 and 2 here.
-
we didn't have time left to address the options of side panel and pop-up in this frame.
@slemeur FYI
Latest UI suggestion for review: https://miro.com/app/board/uXjVIJnYtgc=/?moveToWidget=3458764627891954924&cot=14
@Firewall and I reviewed the UI and as the next step I will create a UI for mixed search results (commands + docs + blog posts). We also discussed updating the shortcut to access the command palette to something more universal and findable.
@Firewall I put together a quick representation of what we talked about. I suppose the labels can be helpful, so we don't rely on icons alone, since we might be getting rid of the sections titles and mixing things up. Let's discuss the icons and fields sizes?
Looking great @MariaLeonova!
I agree that the extra labels are helpful, and with them being at the end they are out of the way if you want to just ignore them.
The text for the non-selected items is quite hard to read for me. Don't we usually use a more white instead of grey?
The text for the non-selected items is quite hard to read for me. Don't we usually use a more white instead of grey?
Let me create a better version for this UI!
That is much clearer imo! Shall we share it so we can get feedback?
Of course! What would be the best channels to use?
Following the discussion with the team, I would suggest we keep the command palette somewhat separate, but mention it in the modal anyway, so people can access it if they choose to do so:
Otherwise the search results should be ok as they are in this screen. @Firewall please review.
After discussion, I will put together one more iteration for single search for everything (containers, pods, docs, etc), not just docs. We can try the top level search in the top bar.
adding the link to this issue as well: https://www.figma.com/design/IfJYttlkkly5wNiD28sMY9/Search-Flow?node-id=52-2937&t=ts2Pkccbfi83OO3o-1
Adding a screenshot for the latest iteration. The users need to be able to search everything. At the Ux review we agree that commands might be the first thing they would want to access. They should also be able to search the entire product (containers, pods, etc.) Could we call that files? Or resources?
We also discussed the possibility to bring up commands with a key (similar to cursor and vscode). I updated the figma file - adding a screenshot here, as well:
@MariaLeonova
Could we call that files? Or resources?
I don't think files is a good fit. Resources is better but we area already use Resources in another way. I think it makes more sense to say "Search though containers, pods, deployments, images and more"
I also explored an option to have tabs, let's pick the one that works best. Just for reference, VScode and Cursor have a list. And Docker Desktop has tabs.
Option 1. List
Option 2. Tabs
My personal preference is tabs, it seems to me that in that case it's clearer to understand what exactly one is searching through at the moment.
There's also naming decisions to be made, I wonder if we should involve someone from documentation for help? I.e. what to call the combined containers, images, pods etc group (everything, in short). Should it be assets?
What should the search bar say once the user clicks into it? Here I have suggested two different options.
Search Podman Desktop, browse documentation or press > for commands or Search containers, pods, deployments, images and more.
Maybe "Infrastructure" could be considered as an umbrella word for all the assets? As for the placeholder, I think we should find out what all components/assets we support searching for to not promise something we can't fulfill. At the first sight it seems that eventually searchable entities are:
- containers
- pods
- images
- volumes
- Kubernetes - nodes
- Kubernetes - deployments
- Kubernetes - pods
- Kubernetes - services
- Kubernetes - Ingresses and routes
- Kubernetes - PVCs
- Kubernetes - Configmaps and secrets
- Kubernetes - jobs
- Kubernetes - cronjobs
- Extensions?
Not sure if it helps with the naming, but at least we can see that the scope of the search may grow rapidly depending on how we set boundaries.
Anyways, I like the design, tabs may work well
Visually I like the tabs, but in the second/tab screenshot above it's not clear what key I could press to switch to commands ('>' in the first screenshot). Could be fixed by having the All/root content be more like the first screenshot.
The main drawback is that the tabs are always visible though. This means there's always a large gap between what I'm typing and the content it's affecting. If I pressed F1 to get to Commands, I don't need/want this visual reminder that I could go to Documentation always in the way. For this reason alone I'd say the 'root' screen could be more visual, but once you go into a category it should be simple.
Re: Asset naming, how about just Go To, Search, or Find? VS Code uses Go To.
Thank you for the suggestions! Too bad Resources is already taken, it would have been perfect in this context.
After some consideration, I think I'll go with the tab layout.
Pressing each respective shortcut will switch to the appropriate tab.
Pressing > will bring up the commands list:
Looking better every time!
Few questions:
- Shortcuts for commands on
F1and Documenation on Ctrl + K feels the opposite way around. - I personally don't like
Assetsat all, but also it is out of scope for this ticket, so I think we can leave the exact name choice for later - What happens when I start typing in the first screen? I guess it will show results under the
Alltab, how are commands/documentation differenciated? - The
Recentresults, will it berecent selected results? orrecent searched terms. I thinkrecent selected resultsbut can you confirm? You could typecontainand the select theCreate a pod from selected containers. I think it makes mosst sense if theCreate a pod from selected containersis the part that shows up in the Recent list
- I rearranged them - please see if this is better?
- we can say Go to, as Tim suggested in his comment
- I am adding a screenshot of a proposal (Figma)
- I'll address this next :)