istio.io
istio.io copied to clipboard
istio
Documentation unreadable in Chrome
Is this the right place to submit this?
- [X] This is not a security vulnerability or a crashing bug
- [X] This is not a question about how to use Istio
Bug Description
The layout of tabular data within e.g. https://istio.io/latest/docs/reference/config/istio.mesh.v1alpha1/#ProxyConfig prevents reading it. The fixed width is narrower than the contained table even on a very wide screen. Zooming in and out delivers no benefit since it consistently zooms all scaling, including both the fixed width and the font size.
A workaround on my Chrome was to open the inspector and edit the style for .docs.container to be 2000px
Version
N/A
Additional Information
No response
@cefn I didn't find any problems, there is a table with horizontal scrolling, if i remove it it will be even worse.
The only thing I found is a very long title https://istio.io/latest/docs/reference/config/istio.mesh.v1alpha1/#MeshConfig-ExtensionProvider-EnvoyExternalAuthorizationRequestBody
I use chrome to
Can you send me a screenshot of the MeshConfig and ProxyConfig tables, then? Here are screenshots.
The fact this table is too wide for the viewport makes this reference documentation unusable in my opinion (for my browser config). Take the ProxyConfig table. There is a whole invisible 'Requirements' column and no control to get to it.
https://istio.io/latest/docs/reference/config/istio.mesh.v1alpha1/#ProxyConfig
Can you send me a screenshot of the MeshConfig and ProxyConfig tables, then? Here are screenshots.
The fact this table is too wide for the viewport makes this reference documentation unusable in my opinion (for my browser config). Take the ProxyConfig table. There is a whole invisible 'Requirements' column and no control to get to it.
https://istio.io/latest/docs/reference/config/istio.mesh.v1alpha1/#ProxyConfig
That's right, that's how it should work, there is a scroll bar for the table at the bottom, you should understand that everything depends on the content.
If you make a table without scrolling it will be like this
If you are interested, I checked the same content at https://getbootstrap.com/docs/5.3/content/tables/#always-responsive in their tables, and there is a similar solution with scrolling.
@cefn Thanks for the report. I'm not sure we can do much more without a fundamental change to how we present this data (e.g. not having a TOC on the right). I know we've had to do this to stop line breaking as arhell pointed out above. Do you see the scrollbar at the bottom of the table?
If you make a table without scrolling it will be like this
CSS allows the designer to determine the width and sharing strategy for different 'cells'. Here, the field and type cells to the left need a minimum dedicated em and the text description needs to fill the remainder. With this change, in my view, it's trivial for everything to fit within the width.
However, minimum width of the content section is already an optional design conceit and must have corresponding decisions about information layout or shouldn't be adopted. At the very least it could be fixed for wider screens by either introducing a wide-screen breakpoint or setting the default desktop breakpoint higher (1200 is reasonable these days) or ensuring that minwidth for the desktop breakpoint is determined by percentage not pixels. Then at least the typical display devices for software professionals can consume the information.
If you want to see how absurd the minwidth design conceit is, given the consequences for the core purpose of this page, consider this screenshot on my main monitor. Claiming there is no way for the text to fit horizontally in the screen is false. For this use case, the designer needs to reconsider the minwidth behaviour, which settles to approximately 900 pixels on my 3440 pixel viewport.
Do you see the scrollbar at the bottom of the table?
Not in any real-world scenario, such as the ProxyConfig. Looking at any particular row (in the original view where you can see the name of it) you can then scroll several screen-heights to see the horizontal scrollbar, then scroll it horizontally, and when you scroll back vertically you can see the description, but no identifier, making it impossible to use as per the very first screenshot in this thread.
I genuinely struggle to understand how this is considered to be usable or a good idea, maybe it's different in my browser or something but have you tried to read a description of any named parameter in ProxyConfig? After testing it, what was your experience?
As per my original report, fixing it for my viewport involves setting a single CSS property so I disagree with the claim ' I'm not sure we can do much more without a fundamental change to how we present this data'. The question is simply whether the individual involved in making the CSS design decisions is willing to reconsider their choices and identify a solution in the face of user experience testing.
the individual involved in making the CSS design decisions
As with so many open source projects, we don't really have one of those. The site was created about eight years ago, and reskinned about four years ago. None of the people involved are still around.
We have a couple of occasional volunteers, including Arhell, who will tweak styles, but we don't have any regular contributor who knows CSS at the level you are talking at.
That said, I am an individual with the ability to accept changes. If you're able to submit one, or give enough guidance to someone else that they can make one, i will very happily shepherd it through!
Thanks for the offer and it's of course a very reasonable position for an open source project to take. I am the user population's worst nightmare when it comes to styling and formatting (I have no aesthetic sense whatever as my colleagues would attest).
For now I have found a workaround, since if I make my viewport SMALLER than 1200 pixels the table seems to get the expected treatment (although the Field and Type columns are unnecessarily large at least everything is visible and readable and it's the description column that scales up and down to accommodate restricted width.
I assume that resizing to that width removed the page table of contents on the right?
Hey @cefn,
How do you feel about this? https://github.com/istio/istio.io/pull/16076
The changes have landed. Here is the result for the example shown earlier:
Closing this particular issue. There will be more, especially around mobile (no attempt was made) and some URLs in text that should become anchor tags. Please open more issues for specific things if you wish.