Clicking on the library tile should directly lead to library docs
Opened this issue · 17 comments
https://www.preview.boost.org/libraries/
Clicking on the library tiles leads to the library readme in the git repository (if there is one). From there, it is not clear how to get to the documentation. There is a link, but it's not immediately visible.
I think, clicking on the library should immediately lead to the library documentation, or at least it should be easy to get to the library docs immediately from the library list. Any other resources, such as activity, list of maintainers, etc. is secondary; it may be reachable, but the main purpose of the library list should be directing the user to the library docs.
The readme in git is typically a placeholder for people browsing GitHub, its main purpose is to redirect the viewer to the Boost website and associated resources. There's no use to show it on the website as well.
If you are on the top libraries page https://www.preview.boost.org/libraries/ and click on a library, it goes to a dedicated library page such as https://www.preview.boost.org/libraries/filesystem/boost-1-84-0/ , of which the README is only one part.
The page shows a few links, the top one is Documentation:
Perhaps on the top level libraries page https://www.preview.boost.org/libraries/ on each library tile, in the upper right side of the tile, there could be a very small image of a book, open or closed,
which is a hyperlink that goes directly to the docs of that library.
@sdarwin I like that idea. There are some libraries in prior releases where there may not be a direct link, and instead the link we provide is to the overall release docs page- but I think that would still be fine, it's still a nice easy shortcut to get a user to a place they are likely to want to be going.
Although, it's a trade-off. The full library page https://www.preview.boost.org/libraries/filesystem/boost-1-84-0/ has a more complete set of information. Adding the direct docs link might cause users to skip that page entirely. Every time.
Perhaps yet another icon, next to the book, which goes to the libraries/filesystem/boost-1-84-0/ page. But, not sure.
If you are on the top libraries page https://www.preview.boost.org/libraries/ and click on a library, it goes to a dedicated library page such as https://www.preview.boost.org/libraries/filesystem/boost-1-84-0/ , of which the README is only one part.
Yes, and I'm asking to remove that stopgap page. I think the tile in the library list should lead to the library docs by default. You can add a small icon (like an "i" in a circle or something) leading to auxiliary information like stats and maintainers and whatnot.
My point is that the majority of viewers visit the library list to get to the library docs, and that should be the primary function requiring the least amount of clicks, reading or aiming with the cursor.
So maybe two icons, side by side:
- "an "i" in a circle or something"
- a book
Again, I think, "a book" should not be needed and the tile (or the library name) should lead to docs directly.
should lead to docs directly
That is your opinion, which is that the users are only interested in docs.
However the current dedicated library page is more of an introduction, with links to the repo, the author, the commit chart, the docs. It's an overview. Some visitors are exploring the website and learning about libraries.
Yes, and I'm asking to remove that stopgap page. I think the tile in the library list should lead to the library docs by default.
To be clear, what you are asking is for us to discard the work that we did and instead revert to the old website behavior. Our desire for the library landing page is to give new users additional context and information that will help inform their decision to use Boost, or a particular library. If your issue is the number of clicks, we can consider adding an icon to the tile itself taking you straight to the docs.
There was not a single time when I wanted to see the readme of a library. Literally. The whole purpose of a readme is to redirect the viewer to the library docs proper. And the only purpose for visiting the library list is, again, to get to the library docs as fast as possible. This was my experience with Boost for decades. I don't see the reason why getting to library docs should be longer (in terms of clicks and navigation) and less convenient in the new website.
So yes, I'm asking to revert to the old site behavior because I consider the stopgap page as a regression in usability. Regarding throwing away some work - I'm sorry if you spent time and money on this but if it isn't working for the better of usability then yes, it should be thrown away. Maybe you can salvage it in some way, as long as it doesn't interfere with the primary use case of the library list.
I think we can add a "Docs" link of some kind on the Libraries page, for each library. Perhaps an icon, text link, or both. That said, I think the assumption that every person on the planet uses the website in exactly the same way is likely false.
I think that a decently-prominent icon or link in each panel can be done in a way where it will be extremely obvious that clicking it would go directly to the docs.
We could add a bit of text at the top of the page, "To directly view the documentation for a library, use the quick access icon [icon here]. For (additional/supplemental) information about the library, please click the title." Something like that, at least.
But I have a feeling the type of user who will want to go directly to the docs would at worst make the mistake once of getting to the intermediary page (for their workflow), even without that text at the top. (and if we don't add text like that, we'll have the title attribute set for the links no matter what, so a tooltip would show on hover to say what the action is)
Can we please see some mockups with a few choices to help decide?
Here's a quick mock-up that has 3 ways of using an icon in the top left. I believe I have them vertically-aligned to the middle of the library title, but I did this in Photoshop so in the event alignments are off, that's not something to worry about here.
Let me know if you want to see other options.
Ideally over time we will begin to have or we will think of additional information to have on the library detail page. That's what I would plan for. At the moment, @Lastique is seeing that basically all of that info on the detail page likely could fit into these panels - and I will always want users to have a path requiring the least clicks for most-used features - that's why I think having the doc link here is a great idea. (Analytics over time is the best way to determine this, but I think it's obvious that the docs are going to be the top action here)
Some potential ideas for the detail page while I'm thinking about it, in case it helps to see the justification for the page:
- allowing user comments (moderated - doubtful that we would want to turn it into a type of discussion thread, but if a person has great revelant info that isn't a great fit for the docs, that could be nice).
- links to projects implementing the library.
- additional charts / data- number of downloads; number of projects that can be found using it if that's feasible ("found in at least 23 projects.."); number of views of the library's detail page and/or docs page (could lead to a sort by popularity/most viewed option)
- links to other libraries by the same authors/maintainers
Not a fan of "Direct to Docs" text but an icon could work, it needs to be toned down a little bit. And how are the other views (lists, etc)
Andrey how do you feel about this?
Well, I've already said that I think the tile itself should lead to the library docs, so no icon for docs should be necessary. An icon for stats/readme might be.
But if I have to choose between the three variants presented in #938 (comment) then the left one looks ok. The right one is also ok but the "Docs" might get in the way if you're planning on adding more icons in the future. As an idea, you could integrate "Docs" into the icon.
The "Quick Guide: ..." writing at the top is too small and I don't think people will notice it. If you go with icons, it should be immediately apparent what the icons do, and that writing should not be necessary.
@4down lets go with the first one then with just the icon. I don't think you should include the text explaining to people where to click. And we will need to design the list and category views as well.
@vinniefalco Got it. Prioritizing #993 since I'd like to get that on production, and will have this on staging for review after. I'll take care of all views, thanks for the reminder on that.
If for any of the other views it seems like posting a mock-up here first might save time, I'll do that, but I think it will be the same amount of time to make a mock-up as it is to go ahead and do what will maintain consistency and is easily usable directly, and we can tweak from there as needed on staging.