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

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

Open
mvdan opened this issue Nov 17, 2020 · 10 comments
Open

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

mvdan opened this issue Nov 17, 2020 · 10 comments

Comments

@mvdan
Copy link
Member

@mvdan mvdan commented Nov 17, 2020

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.

@mvdan mvdan added the pkgsite label Nov 17, 2020
@gopherbot gopherbot added this to the Unreleased milestone Nov 17, 2020
@jamalc jamalc modified the milestones: Unreleased, pkgsite/dochtml Nov 17, 2020
@julieqiu
Copy link
Contributor

@julieqiu julieqiu commented Nov 17, 2020

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
Copy link
Contributor

@cespare cespare commented Nov 17, 2020

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
Copy link
Member Author

@mvdan mvdan commented Nov 18, 2020

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
Copy link
Contributor

@julieqiu julieqiu commented Nov 18, 2020

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 julieqiu added the UX label Nov 18, 2020
@julieqiu
Copy link
Contributor

@julieqiu julieqiu commented Nov 18, 2020

@gopherbot
Copy link

@gopherbot gopherbot commented Nov 18, 2020

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

@mvdan
Copy link
Member Author

@mvdan mvdan commented Nov 18, 2020

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?

@Joanne881107
Copy link

@Joanne881107 Joanne881107 commented Nov 18, 2020

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
Copy link

@fflewddur fflewddur commented Nov 19, 2020

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.

gopherbot pushed a commit to golang/pkgsite that referenced this issue Nov 19, 2020
When a documentation section is empty, the text now displays "This
section is empty."

For golang/go#42652

Change-Id: I9dca537823d8e8aeb5adcb2404e02153ee025ef6
Reviewed-on: https://go-review.googlesource.com/c/pkgsite/+/271257
Trust: Julie Qiu <julie@golang.org>
Run-TryBot: Julie Qiu <julie@golang.org>
TryBot-Result: kokoro <noreply+kokoro@google.com>
Reviewed-by: Jamal Carvalho <jamal@golang.org>
@cespare
Copy link
Contributor

@cespare cespare commented Nov 19, 2020

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
7 participants
You can’t perform that action at this time.