[Resolved] Short. vs Long linkTitle

[svrnm]

Taking this discussion out of #4966 and #4853:

To make the new proposed information architecture successful, we need to consider to rethink our preference for short (or very short) linkTitle, which will be used in the side navigation presented to end users. One example among a few is "SDK" vs "Managing telemetry with the SDK" (see #4966 (comment)).

I expressed my concerns in this comment:

My only issue with the structure is that for a person not involved in OpenTelemetry (or observability) the structure will not help them to navigate, since they might know what an API & SDK are, but not know immediately what the difference is.

So if we go with "SDK" we have to assume that people read some of the introductions to understand what to expected when they click on it. My assumption is always that people read nothing and just look for the one thing they currently care about (e.g. "managing telemetry" or "capture telemetry"), so they will not find that if the title is "SDK" and will tell that our documentation sucks.

I'd like to understand from @open-telemetry/docs-maintainers, @open-telemetry/docs-approvers and others, what your preference is and what advantages you see between the one or the other?

We need to make a decision eventually, and then write this down in our contribution guidelines.

[theletterf]

Thanks for raising this. I'd rather go with long linkTitles (though within reason). Why?

Because...

• They are clearer for all, including localizers and users with impaired vision using screen readers.
• We shouldn't be slaves of the standard desktop layout. In mobile views, the question doesn't make sense:

Kubernets is following that path already, it seems: https://kubernetes.io/docs/setup/production-environment/tools/

[chalin]

Works for me, but at some point we'll want to keep some balance. With too many line wraps due to long titles in the left nav, it'll be difficult to parse / read.

[svrnm]

Yes, we need to keep a balance here. Can we enforce a character limit somehow? Maybe some of our linters can help with that? We can still decide to raise that limit from time to time, but at least we keep track of it.

[theletterf]

I think 50 characters is a good limit — it'd translate to a double-line menu item in most desktop resolutions. Below is a 37 char example borrowed from Noam Chomsky.

[svrnm]

Yes, something between 40 and 50 was also what I was thinking about.

[chalin]

Let's track this idea via:

• [infra] Enforce a character limit on explicit or implicit linkTitle #5152

[svrnm]

Since we all agree that we are OK with longer titles to accomplish more clarity, I will close this discussion now. If we ever need to revisit this decision, let's have a new discussion