Re-design of the NuGet.org Package Details page #10867
Conversation
|
|
jcjiang
changed the title
JonDouglas
requested review from
agr,
anangaur,
chrisraygill,
dannyjdev,
drewgillies,
joelverhagen,
loic-sharma,
lyndaidaii,
shishirx34,
skofman1,
sophiamfavro and
a team
|
I mentioned on Twitter, that the focus on the install bar is probably not helpful to devs and takes up a lot of visual real estate. What if we moved it to the right-hand bar and put more of an emphasis on the contents of the package?
|
|
IMO, it's a bit weird to give the README this much presence at this point in time. While it may be at the same top place today, the current state of affairs is most packages (even the top ones) seem to have 1-2 lines of text there max (am I way off here? maybe analysis has been done already). The current design pushes the other content out of view and seems like it'd be less accessible. Today the #1 thing I'm looking at is dependencies, so much so that I have a user script that keeps that element expanded (it'd be nice if NuGet just remembered this - even For my personal use case, I'd love to see which frameworks a package was built for, and how many dependencies it has - that can likely be a sidebar item, that deep links to the tab. I'm not sure if that's a minority use case though. It's not directly related to this proposal but as a package author I really can't see release notes taking off and deserving a UI redesign around - as a part of the package that's shipped/immutable and cannot be adjusted, I'm always going to opt to keep my release notes at a URL elsewhere. Do we know how many packages might use this? I know that in #1203 there's a proposal to embed a README file in there from a path (which I agree with if used at all), but it's still immutable, and I'd definitely still just link out to readme notes. That's a rather long way of saying I guess: can we instead let me have release notes as a URL, and put it in the sidebar if it is one - save the tab. |
|
Echoing twitter also, my feedback:
Big agree. Sidebar frameworks, and keep the framework tabs for a deep dive. |
|
My initial reaction is that all of the links on the right blend in - it's a sea of blue, that a user needs to parse to understand what's going on. The icons are small enough, that the differentiation is barely noticeable. |
As a package maintainer, I agree. I don't want to duplicate content from a website or from github repo to a nuget page, so I simply leave a couple of references to resources there. |
|
@WhiteBlackGoose thanks for commenting! I have a couple questions:
|
That's a fairly standard pattern, though @WhiteBlackGoose - for example, here is a package example on PyPI: https://pypi.org/project/gee2drive/ The same content is in the README: https://github.com/samapriya/gee2drive I wouldn't expect every package user to go to GitHub to learn all the details, and speaking here as a dev myself - it's convenient to get the information where the package is. |
I'm taking my words back, now it sounds cool. I missed that post so assumed that there would be some limited version of readme and, as a result, I'd need to work on another version of readme specifically for nuget. If it is not so... sounds great then. With all this said, of course, readme should be the first tab. |
|
@dend if I recall correctly, the last time I tried to upload my whole readme, it responded that it's too long 😕 . Let's see how the new version works, I'll surely try it as soon as it's released. |
|
Hi @NickCraver ! Thanks for the thorough and thoughtful feedback 😊 I have a couple thoughts:
You're 100% correct that most packages don't have READMEs yet. The legacy README experience had low adoption and the new embedded README feature is still in preview. That being said, all the mockups for the NuGet.org details re-design are thinking forward to when embedded READMEs have more adoption. Our hope is that README being the default tab will have the following effects:
What do you see as the benefit of a sidebar item deep-linked to a tab vs. just clicking on the tab? Stands out more visually?
What makes you prefer a release notes URL over embedded markdown release notes like the new embedded README feature? It's true that it's immutable, but it should automatically pack the latest version of your changelog/release notes along with the package once you have it defined in your project file. It shouldn't be any additional overhead to update it on NuGet.org with each release beyond updating the document you maintain in your repo that you would otherwise link to. The benefit of embedding it is that we can surface it directly on NuGet.org for much easier accessibility and a more consistent experience across packages. We may also be able to parse it to surface relevant information in client products like VS. Other ecosystems like pub.dev already use this approach: https://pub.dev/packages/http/changelog. Thanks again for the feedback! |
|
Welcome! Answers below:
To be clear: it wouldn't be just a link in the sidebar, but a section listing the frameworks, something like: Dependencies:
...and each could deep link to the tab for listing dependencies.
The fact that it's immutable is the main thing. You cannot amend releases notes for a release. Didn't get a link right? Didn't credit someone correctly? Didn't include a change that made it in? Didn't make a critical breaking release note that's causing a lot if issues to be filed? Things like this happen, and "just updating them next release" doesn't even work as a solution because when looking at an old version and it's release notes...you're hosed. If they're on GitHub, in the repo, GitHub pages, etc.? Easy to fix. If I fix them there, all we have is a skew between what was published and the updated version. And so, you won't find me updating this feature...I'll be updating the source-of-truth we have today, at a URL, without all of the immutability drawbacks. Overall: it may benefit the NuGet team and users to have it right there, but it does not benefit me as a maintainer - it introduces restrictions and headaches. So as a maintainer, I wouldn't use this feature - I may be an outlier though, but want to convey that feedback so it's a known scenario. |
|
The idea to use the README as description, would definitely be a great improvement over the current package description.
Would love to see the supported frameworks in a prominent area, without any navigation. |
|
@arpadbarta what kind of information are you looking for in the "dependencies"? How many there are, whether or not your trust them, if they're mostly 1st or third party, etc. |
This makes a lot of sense to me, and I agree that it should help drive embedded README adoption. When I'm evaluating a NuGet package, the first thing I want to know is what it's for. Package authors are in the best position to communicate that. After I know whether it might meet my needs, I start looking at dependencies, reputation, and other indicators. Those are important, but they are secondary to understanding what the package does.
I understand the value of making release notes immutable, but I agree that it sets the bar pretty high for the level of maturity required to achieve that. One thing that would help is documented examples of automated build pipelines on a variety of popular CI/CD services that demonstrate a strategy for versioning, maintaining release notes, and publishing to NuGet.org. Alternatively, perhaps it would be possible to support publishing a NuGet package in a private draft status that allows online revisions to the release notes (and possibly embedded README) before signing (when not already signed by the author) and public release. |
Definitely the number of them and their source. Have not thought about grouping/or differentiating somehow based on their publisher (First party and others), however that could be helpful. |
|
@khalidabuhakmeh Sweet design! Yeah, the placement of the installation bar was something our team went back and forth on a lot. We had heard a bunch of varying opinions on how useful that bar was and we weren't sure if the difference was because of people's experience levels. We weren't sure if the installation bar was helpful for someone just starting out, or if it would just bombard them with information they don't know how to make sense of - or don't need. I'm curious about your experience (and that of anyone reading!) with the installation bar, especially over time. Did you use it often at any point? When would you use it? When would you not? I'm wondering if there are some situations where the installation bar is super helpful and others where it's pretty useless. @NickCraver REALLY appreciate the thoughts. Thanks for bringing up Release Notes - that's something I honestly always felt weird having as it is now, an immutable blob of text with no clear separation of versions. We were considering combining the Release Notes and Versions tab, with the (usually URL) notes beside the version for easy scanning. Here's what it would have looked like:
I'm thinking that we could check Release Notes text input for URLs and then link directly to them, potentially right next to each version so you can select from a high-level view. What do you think? |
|
@jcjiang I find the current bar not helpful since more users will end up using their tooling to find and install packages. Whether that be through Visual Studio, JetBrains Rider, or Visual Studio Code. The explicit version number is also more annoying. What is useful is the package name and if there is a difference in the installation process. (i.e. library dependency, templates, etc.). Either way, I think the initial redesign is an improvement over what is there currently. Cheers! |
|
@RichiCoder1 @arpadbarta @NickCraver Thanks for bringing up frameworks! We actually have something in the works right now to show a package's target frameworks in two places on the page - badges in the header (and maybe eventually on the package search results page) and the dedicated Frameworks tab for a deep dive. This is what it might look like:
and in the header:
As you can tell by the mock-ups, we're still making a few final decisions for the badges. One thought is to replace the colored-background .NET text with 'Target Frameworks' instead, to lessen confusion about what the badges indicate. Any parts you find confusing or would want changed? |
I think it's a neat approach, but as an addon author I would always point it at a single URL (so I think it would just repeat here?) If that's an acceptable use case: awesome, works for me!
It's nice to list the frameworks it's built for, but I wonder if the research is potentially a bit dated over time here. For a while there, it was very relevant if your package was build for a particular framework (e.g. is this ready for .NET Core yet?) but that becomes less relevant and we can almost tell by the date alone. What I'm interested in is what the UI today actually does a better job of: what does it cost me? e.g. "what are the dependencies, on the version I'm after?" It could be a weight issue, a license issue, or something else. I always want to see the dependencies I'd be pulling in, but maybe that's a minority use case...I have no idea! |
|
As a package author I don't want to maintain a readme, changelog, or release notes outside of my repo nor do I want to deal with syncing them between environments (github, docs, wiki, nuget, etc.). My repos all have a readme, changelog, tag, and usually a github release with a copy of the changelog and any release notes. All of this can now be automated with github actions. It's also not uncommon to have to edit these later on which is why I never include it in the nupkg or try to add it to nuget.org. If sourcelink is used, or a repo url is provided, all of these things should automatically be pulled in and linked to. That would reduce the maintenance burden and hopefully increase the quality of information for all packages. When looking at nuget.org the only project information I expect to see is the readme and a link to the repo. Release notes have never been relevant when searching for a package, they are relevant during updates though which dependabot handles by pulling that info from the project's repo. For anyone manually updating, having a link on the right side of the package's page to the changelog and a link to the release (if available) alongside each version feels like it should be sufficient enough. Overall I think whatever can be done to simplify publishing and maintaining packages in the registry should be the goal. When I compare what I need to do to setup and publish to npm vs. nuget it's pretty overwhelming. I like the new readme support, but it feels like this should happen automatically and not require opting-in or configuring anything. Even simple things like a package icon feel like overkill to me. |
@xt0rted Thanks for your comment. Seems @loic-sharma agrees with you 😄: Show ⬆️ some love by upvoting it and also providing your input. I think you go beyond the issue by asking for some auto include of artifacts. /cc: @chgill-MSFT |
|
Overall the new designs look great! Most of my comments are just suggestions to consider, but I think this is already going in a good direction! |
| - Personal site | ||
| - Source repository | ||
| - License | ||
| - Download package |
There was a problem hiding this comment.
It might be helpful if we had an info icon or similar after the "Downlod symbols" link because many people might not know what it's for.
There was a problem hiding this comment.
@loic-sharma @sophiamfavro Do you know of any good resources explaining why and how one would download symbols? Maybe we can link from the page
| - External links | ||
| - Personal site | ||
| - Source repository | ||
| - License |
There was a problem hiding this comment.
Is the typical symbol for a license the checkmark with ribbons? GitHub uses the balancing scales icon, which we may want to consider for consistency.
There was a problem hiding this comment.
Unsure, but it is the current symbol used by NuGet.org to denote license and we decided to do a direct port for this re-design (leaving additional improvements to what/how information is presented for future iterations.) Definitely something we should look at later on though
| Tabs with titles that clearly convey what information is in them. | ||
|
|
||
| **Requirements:** | ||
| - README Tab |
There was a problem hiding this comment.
Consider changing the capitalization to "Readme". All caps looks a little loud and distracting compared to the other tab labels. While "README" is frequently used in documentation, both Pub.Dev and NPM use "Readme" in tab labels, probably for the reason stated above 😊
There was a problem hiding this comment.
Great point about the difference in usage within documentation vs. tab labels! For easy reference, this is what pub.dev and NPM looks like:
@loic-sharma @sophiamfavro What do you two think?
| - Title | ||
| - Icon | ||
| - Hidden for packages without icon | ||
| - Version |
There was a problem hiding this comment.
Consider showing when the version being viewed was published. Based on feedback in the issue and customer interviews, how "updated" a package is is a critical detail. It may also be worthwhile to surface the last time to package was updated as a whole in the sidebar.
There was a problem hiding this comment.
Love it! Will make the edit
|
|
||
| Information that needs to be seen at a glance such as package ID, description, and eventually, TFM badges. | ||
|
|
||
| **Requirements** |
There was a problem hiding this comment.
We should consider how our current warnings/notifications will look on the new design if at all different. There's a box that pops up for:
- Package is indexing
- There is a later version of this package
- The package is deprecated
- The package has a vulnerability
and maybe a few other scenarios as well.
There was a problem hiding this comment.
Great point! We talked a bit yesterday about the warnings/vulnerabilities system. The TL;DR is that there is a lot of complexity there (14 different banners with no real rhyme or reason for why some are one color and others are another) and we decided to punt the implementation outside the scope of the project.
We'll keep the current warnings/notifications, but Maryanne and I will work on re-designing them to be more clear and useful so it can be picked up by devs in the future
| - Download statistics | ||
| - Total downloads | ||
| - Downloads of current version | ||
| - Average downloads per day |
There was a problem hiding this comment.
Are downloads per day of the current version or the overall package? We may want to consider only showing 2 of these to save on space and make it more focused.
My vote would be keep Total and Current Version downloads and put the Per Day in the "full stats" page. It may be helpful to get customer feedback on that tho 😊
There was a problem hiding this comment.
Overall package!
That makes sense and I agree that we should be more intentional about what stats we show vs. hide on the "full stats" page. For this work, however, I plan on keeping these three just because they are the three displayed on the current package details page. Good to have a baseline to compare against as we start modifying how/what we show instead of just the way we show information.
There was a problem hiding this comment.
Can we keep a running list of considered small design fixes that we'd like to test out after the initial iteration? My concern being that most of these are minor issues we may struggle to individually prioritize once the bulk of this feature is complete. It'll probably we overall less work to review and address them as we're refining this redesign 😊
Your approach for the initial iteration makes complete sense to me 👍
|
Thanks for all the feedback, folks! Lots of good stuff here. One bit of context here is that this re-design will be the first iteration of many. The main goal here is to do a direct port of information we currently display on the page and displaying it in a more clear way. That way we have a baseline to compare against for later iterations as we include additional data/info to display and/or modify functionality. Here's a summary of topics and responses:
If you have any big "this re-design should not move forward without this change!" comments, now is the time! I'll close this thread end of today so the devs can start implementing this iteration ASAP, and I'll put all the other suggestions together for future iterations. I'll tag y'all in those proposals as well because it would be great to hear your thoughts. |
|
Hey all! Thank you for your help here. I wanted to share that the new redesign of the package details page has gone live and you can see it by navigating to any package on NuGet.org. We have a blogpost about it here: https://devblogs.microsoft.com/nuget/introducing-the-new-nuget-org-package-details-page/ This is a first step and there is definitely a lot more work brought up in this thread that still has to be done. The first of them, displaying target framework compatibility information on NuGet.org, will be coming out sometime in October. Stay tuned! |
|
I've been playing with this most of the morning due to updating a project and its packages. I do appreciate all the effort going into this. I have hit several issues, some of which I didn't think of in mock-up phase. In hopes it'll help, summarizing feedback here and happy to expound on anything: Pros:
Cons:
Requests:
I realized I'm probably an outlier user and my usage here may not be important or the goal, but thus far I do much prefer the previous layout that had a quick scroll to get to all the information available. If the dependencies were expanded (or remembered that you expanded them) in the last layout, it'd have been the only click saver I can think of. I am focused on productivity and in that respect, the new layout is slower to get information out of and harder to link people to (the latter of which can be fixed!). Totally get that this probably isn't designed for my use case, but I hope some of the feedback is useful in some way. |
|
Thanks @NickCraver for taking the time to write such thoughtful and thorough feedback. I opened the following work items to track your suggestions:
We believe that READMEs provide an excellent "getting started" experience for users. This is aligned with .NET 6's theme of making .NET more approachable to new developers and students: dotnet/core#5465. Unfortunately we have a chicken and egg problem. Our old design tucked away the README, so authors weren't aware they could add a README, resulting in very low README adoption. We understand that this transition is a little jarring in the short-term, but we are looking closely at how we can improve README adoption.
Do you switch often between different installation instructions? Could you explain a little more your scenario here?
We received lots of feedback that folks didn't understand the checkmark by itself. We're hoping to reduce customer's confusion by adding the new "Prefix reserved" link to docs for additional context. Thanks for your feedback on the docs, these are good comments we should address! |
Introduction of our re-design concept for the NuGet.org package details page, which allows a developer to access at a glance the information they need to choose and use a package.
Find the rendered spec here.
🎉📦Please provide your comments, concerns, and feedback within this PR. 📦🎉