x/pkgsite: inconsistent terminology when referring to packages makes module landing page confusing #43327
What is the URL of the page with the issue?
What is your user agent?
What did you do?
What did you expect to see?
I wanted to see documentation for the package at the root of the module, and specifically to find out the name that that package declares in its
The path indicated by the URL has the following properties:
Given those properties, I expected to see all of the following on the page, somewhere above the fold:
What did you see instead?
The text was updated successfully, but these errors were encountered:
Thank you for the detailed feedback!
Here's some context on why the page is laid out this way, with some thoughts on possible next steps.
We use the last word in the path for all pages, not just package pages. For example, https://pkg.go.dev/golang.org/x/tools has "tools" as the heading, and https://pkg.go.dev/cmd has "cmd/" as the heading. The "/" is added when the page is just a directory.
Since we deprecated the "/mod" namespace, a given page can be of multiple types (details on these labels in #41586 (comment)), so we wanted a consistent layout for the heading. Additionally, based on UXR studies, we found that having the full module path or import path can cause issues for screen readers, because it results in a confusing speech output.
I wonder if a solution here might be to highlight that the string in the breadcrumb,
We wanted to keep titles in the nav short, which is why we used "Documentation". There are also repositories that use this section to document not just the package, but information for the overall module or repository. For example, https://pkg.go.dev/cloud.google.com/go#section-documentation and https://pkg.go.dev/github.com/aws/aws-sdk-go#section-documentation.
However, given that the intent of this section is for package documentation, it might make sense to add some sort of indicator in the section itself.
The current design is ported over from #38596.
We considered the alternative of having the top level headings be:
However, this seemed to give too much weight to nested modules, especially when most repositories do not have nested modules.
@georgehu is working on an updated design for this section, which will (1) alphabetize nested modules within this section and (2) collapsed packages under the directory. This should make the section seem more like a list of actual directories, so stay tuned!
I think that we want to display the top level headings ("README", "Documentation", "Source Files", "Directories") at all times, so it might make sense reduce the height of the container for the README sub-headings. /cc @jamalc