x/pkgsite: inconsistent terminology when referring to packages makes module landing page confusing

[bcmills]

What is the URL of the page with the issue?

https://pkg.go.dev/github.com/mattn/go-sqlite3

What is your user agent?

Mozilla/5.0 (X11; CrOS x86_64 13505.73.0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/87.0.4280.109 Safari/537.36

Screenshot

What did you do?

1. From https://pkg.go.dev, search for go-sqlite3.
2. Click the first search result.

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 package directive.

The path indicated by the URL has the following properties:

• The module path is github.com/mattn/go-sqlite3, and is correctly indicated by the breadcrumb nav at the top of the page.
• The package path is github.com/mattn/go-sqlite3.
• The package name is sqlite3.
• The heading at the top of the module's README.md is go-sqlite3.

Given those properties, I expected to see all of the following on the page, somewhere above the fold:

• Because sqlite3 is the package name but not the module path, I expected to see the string sqlite3 next to the word “package” but not next to the word “module”.
• Because both the README and the package docs are forms of documentation, I expected to see the word “package” in the left-nav link for the package documentation.
• Because the definition of a “module” is “a collection of packages …”, I expected to see the word “packages” in the left-nav link to the table listing the packages within the module.

What did you see instead?

• The module badge is displayed next to the package name instead of the module path. Since in this case the module path is not the package name, this associates the concept “module” with the wrong identifier, especially since the README itself begins with (a fragment of) the actual module name.
• Because of the large number of README sub-headings, the “Documentation” link is pushed almost below the fold.
• The nav link for the package documentation does not mention the word “package” at all, and does not distinguish between package documentation and other kinds of documentation (such as documentation for the module overall).
• The nav link for the list of packages within the module uses the word “directories” instead of “packages”.
  • This is especially confusing for modules like golang.org/x/tools, where the gopls subdirectory is a separate module. In that case, the subdirectory is pulled to the bottom of the list, instead of appearing inline with the other subdirectories. If the terminology used were “packages” and “modules” instead of simply “directories”, then that separation would make intuitive sense — however, the use of the term “directories” instead sets the expectation that the table should contain an entry for each relevant directory regardless of what kind of entity it corresponds to.
    
    

[julieqiu]

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.

/cc @georgehu @fflewddur @jamalc @jba for input

Because sqlite3 is the package name but not the module path, I expected to see
the string sqlite3 next to the word “package” but not next to the word
“module”.

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, github.com/mattn/go-sqlite3, is the module path, or provide a more context when hovering over the "package" and "module" labels via a tooltip.

Because both the README and the package docs are forms of documentation, I
expected to see the word “package” in the left-nav link for the package
documentation.

The nav link for the package documentation does not mention the word “package” at all, and does not distinguish between package documentation and other kinds of documentation (such as documentation for the module overall).

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.

Because the definition of a “module” is “a collection of packages …”, I
expected to see the word “packages” in the left-nav link to the table listing
the packages within the module.

The nav link for the list of packages within the module uses the word “directories” instead of “packages”.

This is especially confusing for modules like golang.org/x/tools, where the gopls subdirectory is a separate module. In that case, the subdirectory is pulled to the bottom of the list, instead of appearing inline with the other subdirectories. If the terminology used were “packages” and “modules” instead of simply “directories”, then that separation would make intuitive sense — however, the use of the term “directories” instead sets the expectation that the table should contain an entry for each relevant directory regardless of what kind of entity it corresponds to.

The current design is ported over from #38596.

We considered the alternative of having the top level headings be:

• README
• Documentation
• Source Files
• Packages
• Nested Modules

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!

Because of the large number of README sub-headings, the “Documentation” link is pushed almost below the fold.

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