Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

x/pkgsite: rethink module page #38087

Open
tooolbox opened this issue Mar 26, 2020 · 1 comment
Open

x/pkgsite: rethink module page #38087

tooolbox opened this issue Mar 26, 2020 · 1 comment

Comments

@tooolbox
Copy link

@tooolbox tooolbox commented Mar 26, 2020

What is the URL of the page with the issue?

https://pkg.go.dev/mod/github.com/jinzhu/gorm

What is your user agent?

Mozilla/5.0 (Macintosh; Intel Mac OS X 10_13_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/80.0.3987.149 Safari/537.36

Screenshot

Screen Shot 2020-03-25 at 8 23 36 PM

What did you do?

Visited the page.

What did you expect to see?

Useful information related to the module, somehow different than the package page.

(Or, nothing at all.)

What did you see instead?

  • The "module" page contains a subset of the information in the root package--it has nothing new to offer.
  • It's not visually differentiated from the "Overview" tab of a package page, so you can get confused about where you are.
  • The primary link on the page is to itself?

Suggestions

  • Take a moment to consider if this page type is needed at all, given that it doesn't seem to provide any value. (Of course, it could be made to provide value, which are my the next points.)
  • The readme on the main Module page is applicable, suggest that it stays.
  • The primary action above the fold could be links to the packages in the module. Those definitely shouldn't be hidden in one of the tabs. Prior art is GitHub which puts the files & directories above the readme, or Godoc where (if you have no actual code in the package) the subpackages take center stage (check out kubernetes).
  • Suggest losing the self-referential link.
  • Suggest losing the Source Code link; make the Readme header link to it, or stick the source URL next to the Readme header as a link.
  • Suggest displaying the entire go.mod file above the Readme. Unsure if it would be the top item or underneath the package links.
  • Suggest a stronger visual differentiation of the page. It would be an exaggeration, but not by much, to say that the easiest way to know you're on a Module page is by checking the URL for "mod". Suggest using different typesetting, layout, iconography, something. Having the go.mod file at the top would be a good indicator, but something in addition to that wouldn't go amiss.

On displaying the go.mod file, it has a lot of useful data, such as what Go version is expected and what all the dependencies are, including their exact versions, and any replacements used. Factually, it's the only data that is unique to a module as a unit. My suggestion is displaying it exactly as-is, in a code font, but make all of the module references into hyperlinks that take you to that module on pkg.go.dev at the referenced version (tag/commit/etc.). This would include any replace => directives.

Thanks!

@gopherbot gopherbot added this to the Unreleased milestone Mar 26, 2020
@gopherbot gopherbot added the pkgsite label Mar 26, 2020
@julieqiu
Copy link
Contributor

@julieqiu julieqiu commented Apr 6, 2020

Thanks for the feedback! We are planning to address this as part of an upcoming round of UX changes.

/cc @fflewddur

@julieqiu julieqiu changed the title go.dev: rethink module page x/pkgsite: rethink module page Jun 15, 2020
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
3 participants
You can’t perform that action at this time.