x/pkgsite: LHS navigation panel is "lossy"

[myitcv]

What is the URL of the page with the issue?

https://pkg.go.dev/cuelang.org/go/cue?tab=doc

What is your user agent?

Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/85.0.4183.59 Safari/537.36

Screenshot

What did you do?

Visited the page.

What did you expect to see?

An overview of the package API, like the old godoc Index:

https://godoc.org/cuelang.org/go/cue

What did you see instead?

A collapse partial representation of the API. Specifically, per #40577, the API itself is by default hidden, and there is no way to auto-expand it

The representation in the LHS is also heavily condensed in order to fit the space. This leads to a very lossy representation. For example:

func (a *Attribute) Lookup(pos int, key string) (val string, found bool, err error)

gets condensed to (side note: frustratingly I can't copy-paste text from the LHS tree view):

(a) Lookup(pos, key)

So now I can't, at a glance, get a view of the entire API - I have to jump to each item separately because of the lossy LHS display.

This condensed representation is also misleading. Consider:

Build(instances)

which sits under the type Instance node. The actual signature here is:

func Build(instances []*build.Instance) []*Instance

i.e. a slice is returned instead of a Instance or *Instance. Again, this sort of subtle distinction is lost in the condensed view.

IMHO the LHS navigation area is always going to have to compromise in ways that are lossy in general, hence the Index should be brought back.

How then would people navigate through the API?

There is already the f keyboard shortcut that allows you to jump to an identifier.

There might be other means by which the entire index can be shown (in a popup perhaps?) and then clicked to navigate - I hasten to add (in case it's not obvious from the quality of that suggestion) that I'm in no way a UI/UX expert.

[salewski]

Two ideas for restoring the Index content:

1. Introduce a new "Index" tab, perhaps between the existing "Doc" and "Overview" tabs.
2. Introduce an expandable link above the "Overview" header on the existing "Doc" tab

[mholt]

The recent LHS nav changes are problematic.

I would like to add a few points (aka complaints, but I'm trying my best to be constructive) that I hope will be rectified soon.

Note that the LHS nav truncates even very short signatures & identifiers with "...":

The "Types" category unnecessarily prefixes each type name with the word "type", wasting precious space:

Notice how the "Functions" category does not do this (thankfully).

Horizontal space is poorly utilized with the recent redesign. Look at how only ~50% of my screen's width is utilized:

even though there are elements which are getting truncated and are so narrow it's hard to read/use. I'm not saying the content needs to be wider (reading wide paragraphs is not easy), but the nav and spacing between nav and content could be resized/adjusted.

Further, since the redesign I've been unable to browse a package's features effectively, because everything is collapsed. I can't browse the method signatures without clicking through each and every one:

Whereas before I could tell at a glance which function I needed. For example: "I have [these input parameters], and I need a [foobar]. I'll just browse this list of methods... aha! This one takes [my parameters] and returns a [foobar]! That must be the one I need." <-- can't do this anymore.

I really, really hope the recent design changes will be reconsidered soon and prioritized. Pkg.go.dev is way less useful to me now.

[salewski]

[...]
Further, since the redesign I've been unable to browse a package's features effectively, because everything is collapsed. I can't browse the method signatures without clicking through each and every one:
[...]
Whereas before I could tell at a glance which function I needed.
[...]

I agree, and have a comment to similar effect over at #40577 (comment)

[andybons]

Thanks all for the valuable feedback and suggestions.

I’m in agreement that we are not using the amount of horizontal space effectively (see #40577).

As this is the most viewed page on pkg.go.dev by far, we want to ensure everyone that we’re taking this feedback into account and prioritizing accordingly. We understand how crucial this page is to everyone’s workflow and we’ll be working with our UX partners and the community to improve things.

In short, we hear you.

[myitcv]

Thanks @andybons

I’m in agreement that we are not using the amount of horizontal space effectively (see #40577).

Just to clarify, my primary concern is that this format of presentation is lossy and a backwards step compared to the godoc Index. i.e. people (including myself) place real value in being able to review an overview of the API (see also #40715). (Not using the amount of horizontal space effectively is a derivative issue.) Hence my proposal that in the short term the Index view be brought back whilst we work out the best way forward.

[gopherbot]

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

[prattmic]

To add to this, I find it a bit surprising that while the types and functions in a package aren't included in the main content, the examples are. A good example of this is path/filepath.

On multiple occasions in the last few days I've found myself thoughtlessly clicking on the example link for the function I wanted docs for ("Join" in this case), assuming that was the link to the function doc. This actually kind of works, since the example is right below the function doc, but it is not quite right.

In fact, before I realized these were links to examples I thought I'd found a bug where "func Join" was getting hidden under the top banner:

(It is arguably a separate bug that clicking an example link doesn't expand the example)

[dmitshur]

(It is arguably a separate bug that clicking an example link doesn't expand the example)

That is being tracked in #37520.

[empijei]

As I pointed out in #40715 (which is mostly a duplicate of this bug) there is one additional problem here: even if the LHS panel was expanded by default, it would take way more space than it used to. Moreover it is limited in horizontal space so signatures that are too long require a painfully slow mousehover to be read.

(Note: Considering that not everyone is able to use a mouse and that there doesn't seem to be another way to get that information in a visual way this might be also classified as an accessibility issue.)