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: landing page for docs provides no structural information at a glance. #40715

Closed
empijei opened this issue Aug 12, 2020 · 4 comments
Closed
Labels
Documentation FrozenDueToAge pkgsite UX Issues that involve UXD/UXR input
Milestone

Comments

@empijei
Copy link
Contributor

empijei commented Aug 12, 2020

This is a UX issue.

When reading docs on a package there are two important pieces of information a programmer is after: an overview (AKA the package comment) and a list of functions, types and their constructors.

When visiting the old godoc this is how it is presented:
image
As you can see there is the package name, the overview and at a glance you get all you need to construct and use types in the package.

When visiting the new pkg.go.dev this is what the user is presented with:
image
to get the same kind of information of the old doc the user has to click 9 times to expand all folded menus, and it uses way more space.
For a small package like io I had to flip my screen in vertical mode to take the screenshot below.
image
Please also note that the only way to know the parameters of NewSectionReader is to hover it with the mouse as the left pane is not resizable.

It would be nice to have an overview of the package structure, types and functions at a glance, without having to dig into folds. This view:
image
provides no information as it is going to be identical for every package I visit.

Note that this, at least for me, is a big enough reason to stop using pkg.go.dev since it does not provide the information I am always after, but this is a personal opinion and I don't know if others might feel the same.

@gopherbot gopherbot added this to the Unreleased milestone Aug 12, 2020
@myitcv
Copy link
Member

myitcv commented Aug 12, 2020

Possibly a dup of #40612?

@andybons andybons added the UX Issues that involve UXD/UXR input label Aug 12, 2020
@andybons andybons changed the title go.dev: Landing page for docs provides no structural information at a glance. go.dev: landing page for docs provides no structural information at a glance. Aug 12, 2020
@andybons andybons added pkgsite and removed website labels Aug 12, 2020
@andybons andybons changed the title go.dev: landing page for docs provides no structural information at a glance. x/pkgsite: landing page for docs provides no structural information at a glance. Aug 12, 2020
@andybons andybons removed the website label Aug 12, 2020
@andybons
Copy link
Member

@empijei I have a CL to expand all items by default. While I understand this doesn’t cover all of your concerns, would you consider that mitigation sufficient for this bug? We can track further improvements on #40612.

Let me know what you think.

@gopherbot
Copy link

Change https://golang.org/cl/248183 mentions this issue: content/static,internal/fetch/dochtml: expand all nav elements by default

@empijei
Copy link
Contributor Author

empijei commented Aug 13, 2020

This is indeed a dup of #40612, sorry for not finding it.

My bug also adds that the space taken by the fully expanded list is way more than it used to. I'll close this and add the comment on the other bug. Thanks.

@empijei empijei closed this as completed Aug 13, 2020
gopherbot pushed a commit to golang/pkgsite that referenced this issue Aug 13, 2020
…ault

We’ve received feedback that a fully-collapsed side nav prevents users
from being able to see package structure at a glance. Expand all
functions and types by default.

Also updates CSS for the side nav to not show a scroll bar if the
content doesn’t overflow.

Updates golang/go#40612
Fixes golang/go#40715

Change-Id: I22049e394b8705316e1ebe1cb9691c6317c61c5b
Reviewed-on: https://go-review.googlesource.com/c/pkgsite/+/248183
Run-TryBot: Andrew Bonventre <andybons@golang.org>
TryBot-Result: kokoro <noreply+kokoro@google.com>
Reviewed-by: Jamal Carvalho <jamal@golang.org>
@golang golang locked and limited conversation to collaborators Aug 13, 2021
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
Documentation FrozenDueToAge pkgsite UX Issues that involve UXD/UXR input
Projects
None yet
Development

No branches or pull requests

4 participants