Improve the documentation's readability

lx commented

2022-06-29 09:48:04 +00:00

Owner

This issue was originally openned by @adrien on https://git.deuxfleurs.fr/Deuxfleurs/garage/issues/299. Moving it here because it's relevant to this repo.

This issue inventories graphical "bugs" in the documentation, that hurt its lisiblity. Please add comments with checkboxes to list pain points you identified.

When overflowing tables are involved

Taking the S3 Compatibility page as an example, we see that the documentation layout sometime hinders reading the content:

On small screens (e.g. smartphone), the overflowing tables cannot be read. The viewport should be adapted to the size of the biggest table.
On medium-large screens (1600px on mine), the "Page content" aside covers the tables. This aside could be foldable.

This issue was originally openned by @adrien on <https://git.deuxfleurs.fr/Deuxfleurs/garage/issues/299>. Moving it here because it's relevant to this repo. This issue inventories graphical "bugs" in the documentation, that hurt its lisiblity. Please add comments with checkboxes to list pain points you identified. ### When overflowing tables are involved Taking the [S3 Compatibility page](https://garagehq.deuxfleurs.fr/documentation/reference-manual/s3-compatibility/) as an example, we see that the documentation layout sometime hinders reading the content: * [ ] On small screens (e.g. smartphone), the overflowing tables cannot be read. The viewport should be adapted to the size of the biggest table. * [ ] On medium-large screens (1600px on mine), the "Page content" aside covers the tables. This aside could be foldable.

lx referenced this issue from Deuxfleurs/garage

2022-06-29 09:48:20 +00:00

Improve the documentation's readability #299

tixie commented

2024-04-08 17:14:06 +00:00

Owner

I might be able to come with technical solutions, implying each one different levels of changes. I think it might be interesting to have several on the question, maybe try different solutions to see what’s come best.
Because from my experience tables have always been annoying on small screens (smartphones for example, but can be a computer/tablet window in a split layout and so taking o ly half the screen).
And for each kind of table structure and data structure in them some solutions are better depending of the situation.

Some points of I think it’s important to take into account when thinking on each solutions:

On the semantic level, when correctly made, HTML tables comes out if the box with a great data structure for assistive technologies. So “free web accessibility” always good to take. Avoiding CSS hacks and div soups would allow us to keep that.
If we decide that we need two distinct templates/UI components (tables for large screens and something entirely different for smaller screens) it will probably require to have both of those versions in the DOM and display each depending on the viewport’s width (no biggie on that, web engine are optimized enough). However that means that when the moment will comes to modify something here we need to remember there two area to update and test. TLDR: two completely different components = more maintenance effort
And since we’re to improve the experience for mobile user, we have to keep in mind that scrollbars on mobile OS are very discreet: slim, visible only during scroll. So if scrollable zone are created, we need to inform the user their (approximate) position. At least try the best we can.

That being said, the solutions i first think off:

Add and an horizontal scroll to tables + a shadow potentially on each side if you can still scroll in that direction. [Will do a quick prototype to demo].
- good side: very quick fix allowing the data inside table to be accessible in any case
- bad side: it doesn’t really improve data readability for that kind config when table allows quick visual comparison between elements and their properties.
Create a separate layout for small screens, maybe more based around a list of cards.
- good side: we can really think about the best way to organize data for that format on item level
- bad side: I might be more difficult to compare each property between elements
If we find a way to get a layout working good enough for our expectations on small screens, maybe juste remove the tables and keep those layout, maybe with some adjustments but in a mobile first way (it’s more easy to find how to place elements on a big space when you already had to solve those issues on small screens.

I’ll try to extend this message with reference, maybe examples. So that would less abstract.

In the mean time I’ll look at SaaS pricing pages who face some similar requirements: works on mobile but stil being able to compare the different price ranges.

I might be able to come with technical solutions, implying each one different levels of changes. I think it might be interesting to have several on the question, maybe try different solutions to see what’s come best. Because from my experience tables have always been annoying on small screens (smartphones for example, but can be a computer/tablet window in a split layout and so taking o ly half the screen). And for each kind of table structure and data structure in them some solutions are better depending of the situation. Some points of I think it’s important to take into account when thinking on each solutions: 1. On the semantic level, when correctly made, HTML tables comes out if the box with a great data structure for assistive technologies. So “free web accessibility” always good to take. Avoiding CSS hacks and div soups would allow us to keep that. 2. If we decide that we need two distinct templates/UI components (tables for large screens and something entirely different for smaller screens) it will probably require to have both of those versions in the DOM and display each depending on the viewport’s width (no biggie on that, web engine are optimized enough). However that means that when the moment will comes to modify something here we need to remember there two area to update and test. TLDR: two completely different components = more maintenance effort 3. And since we’re to improve the experience for mobile user, we have to keep in mind that scrollbars on mobile OS are very discreet: slim, visible only during scroll. So if scrollable zone are created, we need to inform the user their (approximate) position. At least try the best we can. That being said, the solutions i first think off: 1. Add and an horizontal scroll to tables + a shadow potentially on each side if you can still scroll in that direction. [Will do a quick prototype to demo]. - good side: very quick fix allowing the data inside table to be accessible in any case - bad side: it doesn’t really improve data readability for that kind config when table allows quick visual comparison between elements and their properties. 2. Create a separate layout for small screens, maybe more based around a list of cards. - good side: we can really think about the best way to organize data for that format on item level - bad side: I might be more difficult to compare each property between elements 3. If we find a way to get a layout working good enough for our expectations on small screens, maybe juste remove the tables and keep those layout, maybe with some adjustments but in a mobile first way (it’s more easy to find how to place elements on a big space when you already had to solve those issues on small screens. I’ll try to extend this message with reference, maybe examples. So that would less abstract. In the mean time I’ll look at SaaS pricing pages who face some similar requirements: works on mobile but stil being able to compare the different price ranges.

Improve the documentation's readability #9

When overflowing tables are involved