x/pkgsite: landing page for docs provides no structural information at a glance. #40715
Labels
Documentation
Issues describing a change to documentation.
FrozenDueToAge
pkgsite
UX
Issues that involve UXD/UXR input
Milestone
Comments
|
Possibly a dup of #40612? |
andybons
changed the title
andybons
changed the title
|
Change https://golang.org/cl/248183 mentions this issue: |
|
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. |
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>
Sign up for free
to subscribe to this conversation on GitHub.
Already have an account?
Sign in.
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:
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:
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
ioI had to flip my screen in vertical mode to take the screenshot below.Please also note that the only way to know the parameters of
NewSectionReaderis 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:
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.
The text was updated successfully, but these errors were encountered: