x/pkgsite: slightly confusing "There are no [...] in this package" placeholders

[mvdan]

Look at https://pkg.go.dev/github.com/multiformats/go-multicodec@master, for example. Its API just exposes an enum-like integer type, with some constants of that type, and a method on the type.

All in all, the package has a few dozen exported constants, and one exported function - a method on the type.

However, the API reads like:

Constants
There are no constants in this package.

Variables
There are no variables in this package.

Functions
There are no functions in this package.

Types
type Code
[...]

"There are no constants in this package" feels incorrect to me, just like "no functions". It's made worse by how I read the page in order - first I'm told there are no constants, which confuses me greatly as this package exposes lots of them. Only later do I find them under the "Types" section.

Godoc has none of those problems; as it does not use sections, it just jumps straight to type Code: https://godoc.org/github.com/multiformats/go-multicodec

Perhaps what I'm proposing is to omit the sections entirely, if just one section has any content. Or to omit sections which are empty, because the "There are no XXX in this package" message can be misleading.

[julieqiu]

We chose to include these sections for accessibility reasons. See the "Empty Sections" section of #41587.

the "There are no XXX in this package" message can be misleading.

I would be in favor of changing the messaging if there are suggestions for something that would be clearer.

[cespare]

I think "misleading" understates it. The statement

There are no constants in this package.

is a bald statement of fact that is entirely false.

Similarly if the only function is detected as a "constructor" and it says:

There are no functions in this package.

ISTM that stating false things is much less accessible than an inconsistent ordering or whatever.

[mvdan]

We chose to include these sections for accessibility reasons.

Thanks for that context, I hadn't noticed it. At the end of the day someone has to make a call for the tradeoff between the UI sections being intuitive to someone looking, and the sections being consistent to someone relying on accessibility interfaces.

I would be in favor of changing the messaging if there are suggestions for something that would be clearer.

I'm not sure - at the core level, the message should really say "please omit this section". The way most UIs would implement that is by not showing the section at all. Surely other accessible sites or web apps have solved this kind of problem?

How about This section is empty.? It still conveys the same meaning we want, but it no longer confuses the reader into thinking that, for example, a package has absolutely zero constants simply because they're under the types section.

Another option would be some sort of UI separator like a grey line, to further hint that the sections contain nothing.

[julieqiu]

How about This section is empty.?

I'm in favor of this as an initial fix.

/cc @Joanne881107 @fflewddur @georgehu for additional UX suggestions.

[julieqiu]

Here's a mock for that change on https://pkg.go.dev/github.com/multiformats/go-multicodec@master:

[gopherbot]

Change https://golang.org/cl/271257 mentions this issue: content/static/html/doc: change text for empty sections

[mvdan]

As I see that screenshot now, I can't help but notice that it's a lot of dead space to someone looking/reading. Half a page has no content whatsoever.

Perhaps we could place "This section is empty" to the right of each section header, to reduce the vertical space taken in half?

[jinhongy]

Those section were added because of the A11y requirement and the eager of providing a unified structure for the left nav. However, I would recommend to avoid these empty section since it will take extra space and provide less value to sighted user. Probably we could revisit the decision and sort out a better solution to service the A11y.

[fflewddur]

I like the "This section is empty." wording, unless we can find something even better.

I wonder if ultimately this is an issue with how we're labeling these sections (and arguably, whether these are the right sections to begin with); these are typically showing global variables and functions, whereas the Types section is showing types and their attached methods. If the labels were "Global variables", etc., that might also resolve the confusion.

[cespare]

I think "This section is empty." is still too confusing.

There are constants. So why is the section empty?

I think the text should indicate that the constants live in a different section. Or it should repeat the definitions of the constants in the constants section.

I have a hard time believing that the accessibility benefits of the empty sections outweigh the confusion caused by suggesting that there are no constants when there are, in fact, constants.

[fgergo]

@julieqiu @mvdan
I'd been recently bitten by this: a - for me - unknown package's exported one letter identifier used like this: pkg.E.fun(). What's E? After a couple of confusing minutes it turns out it's a constant, though neither section on the left lists it as an exported identifier. (As an alternative tried to search for E on the html page.)

Are there counter-arguments to @cespare's ideas? Which one is easier to implement?

I think "This section is empty." is still too confusing.

There are constants. So why is the section empty?

I think the text should indicate that the constants live in a different section. Or it should repeat the definitions of the constants in the constants section.

I have a hard time believing that the accessibility benefits of the empty sections outweigh the confusion caused by suggesting that there are no constants when there are, in fact, constants.

[julieqiu]

/cc @golang/pkgsite