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

Jump to bottom

x/pkgsite: Why does pkg.golang.org refer to "directories" when Go more commonly use the term "packages" #45495

Open
lazyhacker opened this issue Apr 10, 2021 · 6 comments
Open

x/pkgsite: Why does pkg.golang.org refer to "directories" when Go more commonly use the term "packages" #45495

lazyhacker opened this issue Apr 10, 2021 · 6 comments
Labels
NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one. pkgsite
Milestone
pkgsite/unplanned

Comments

@lazyhacker
Copy link

What is the URL of the page with the issue?

(example) https://pkg.go.dev/net/http

What is your user agent?

Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/89.0.4389.114 Safari/537.36

Screenshot

image

What did you do?

Visit pkg.golang.org to look at package/module documentation.

What did you expect to see?

On the left menu, a link called "Packages" that links to a module's package documentation.

What did you see instead?

Instead of calling it "packages", it refers to it as "Directories". Go generally refers to "packages". "Directories" gives the impression that it's for browsing the source files. Even the summary description all say "Package xyz implements ..." since the rules is to have the document say "Package xyz...", but the UI says

Directories

cgi
   Package cgi implements CGI (Common Gateway Interface) as specified in RFC 3875.

cookiejar
   Package cookiejar implements an in-memory RFC 6265-compliant http.CookieJar.

Would it make more sense to say "Packages" instead?
@gopherbot gopherbot added this to the Unreleased milestone Apr 10, 2021
@lazyhacker lazyhacker changed the title x/pkgsite: Why does pkg.golang.org refer to "directories" when Go thinks in term of "packages" x/pkgsite: Why does pkg.golang.org refer to "directories" when Go more commonly use the term "packages" Apr 10, 2021
@jba
Copy link
Contributor

jba commented Apr 11, 2021

They're not always packages; sometimes they are directories that hold packages at a deeper level. We couldn't come up with a better term.

@jba jba added the NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one. label Apr 11, 2021
@jba jba modified the milestones: Unreleased, pkgsite/unplanned Apr 11, 2021
@bcmills
Copy link
Contributor

bcmills commented Apr 12, 2021

Duplicate of #43327?

@fzipp
Copy link
Contributor

fzipp commented Apr 13, 2021 •
edited

Technically not all of them are packages, but all leaves of the shown tree are packages, and only packages are linked. The sole purpose of the non-package directories is to group packages. Tree components in user interfaces are usually titled according to the type of the target objects, not the type of the structuring objects.

@lazyhacker
Copy link
Author

It seems like the intention of the section is to show the packages of the module and its package documentation so seems like "Packages" makes sense. Even the sub-directory section on the page looks like its primary intention is allow navigation to sub-package documentation rather then to actually expose the sub-"directories".

@julieqiu
Copy link
Member

This section doesn't just show packages - it also shows nested modules. For example, https://pkg.go.dev/golang.org/x/tools#section-directories shows gopls with a module label.

@fzipp
Copy link
Contributor

fzipp commented May 1, 2021

Maybe it makes sense to split the "Directories" section into three separate sections:

  • Packages
  • Commands
  • Nested Modules

@bcmills bcmills mentioned this issue Jul 24, 2023
Open
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one. pkgsite
Projects
None yet
Milestone
pkgsite/unplanned
Development

No branches or pull requests
6 participants
@fzipp @bcmills @lazyhacker @julieqiu @gopherbot @jba