Docs rs "[+]" ui element does not afford usage clearly

[Firstyear]

In docs.rs, the UI has elements on the page similar to this screenshot:

The UI element is the light grey "[+]".

This element does not clearly afford it's usage: this means people do not see that it is first a UI element at all, and that it's operation is not clear. I and others had to be told how to interact with this as a UI element. (I actually believed it to be a list-item marker like a *).

This ability to understand clearly that elements are firstly part of the UI, and second what their function is, is an important aspect in the psycholocy of design and human interaction.

In this case, to assist with humans being able to determine on visual inspection the behaviour of the "[+]", it may be better to "document" the behaviour with a change such as "[+ expand]" and "[- collapse]". Not only does this now clearly show that the elements have a purpose, it shows obviously what the purpose is. This also may not be a perfect suggestion, but I think that something about this element should be improved.

I would propose that the element "[+]" be improved to more clearly indicate it's existence and operation to users.

See also original issue: #60215

[QuietMisdreavus]

cc @rust-lang/rustdoc @rust-lang/docs (tagging docs team as this is a "docs display" issue)

I'm hesitant to expand the text there, since those unfold markers appear everywhere on the docs page. Adding a full word to them would create a lot of extra text on the page and shift over all the items they appear beside.

Would it be sufficient to give them some kind of alt-text like "collapse/expand documentation"? That way, they could keep their current size but also have a way to show what they do without having to click on them.

[Lonami]

Maybe the main page of the documentation could explain how items are displayed with some examples and what the [+] and such mean?

[Firstyear]

The problem with this, is imagine someone links me to new documentation from a different location? What if I search and and placed deep into the page? Maybe I don't go past the mainpage? This would probably not work, because people won't find the example usage and description of "[+]", and the examples would probably cause more frustration at their "length" and presence.

I think that alt text also isn't good because unless you mouse over it as an element you don't see the text, and the core of the issue is that it currently doesn't visually look like an element you can interact with. I think better changes would be to change it to a distinct item like an arrow ( https://www.w3schools.com/charsets/ref_utf_arrows.asp ), changing the colour to be more distinct, borders to draw attention to it or text to describe it's usage. Even here on github the button is green with "comment" not "green box with tick". Sometimes the extra text is valuable to include ...

Perhaps there are good examples we can draw on from other prominent web libraries or frameworks on how they create lists or content expansion?

[Lonami]

The HTML details tag (<details><summary>Short</summary> Long</details>) looks like this:

Short

Long

[Firstyear]

That seems really good actually: simple, part of standards, probably works with accessibility tools, can be defaulted to open/close based on preference. There may also be ways to customise it’s style to make it more visible too, but I like this suggestion. Thanks!!

[Lonami]

Unfortunately, Microsoft Edge doesn't support the <details> tag, so the best we can do is emulate its look and feel. To make it worse, we can't just make the entire summary clickable, because we already use links there (for example to navigate to the reference of the return type). So perhaps all left is the triangle instead of [+] [-].

How about a text (expand) aligned to the right? That would be less noisy than making the current [+] be [+ expand] and maybe could work.