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