julieqiu
commented
3 years ago 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 https://github.com/golang/go/issues/41586#issuecomment-698591007), 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 https://github.com/golang/go/issues/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
What is the URL of the page with the issue?
https://pkg.go.dev/github.com/mattn/go-sqlite3
What is your user agent?
Screenshot
What did you do?
go-sqlite3.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
packagedirective.The path indicated by the URL has the following properties:
github.com/mattn/go-sqlite3, and is correctly indicated by the breadcrumb nav at the top of the page.github.com/mattn/go-sqlite3.sqlite3.README.mdisgo-sqlite3.Given those properties, I expected to see all of the following on the page, somewhere above the fold:
sqlite3is the package name but not the module path, I expected to see the stringsqlite3next to the word “package” but not next to the word “module”.READMEand the package docs are forms of documentation, I expected to see the word “package” in the left-nav link for the package documentation.What did you see instead?
modulebadge 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 theREADMEitself begins with (a fragment of) the actual module name.golang.org/x/tools, where thegoplssubdirectory 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.