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.

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.

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.

How about This section is empty.?

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

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

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

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

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?

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.

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.

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 @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.

/cc @golang/pkgsite