Help Wanted: Tables aren't consistently formatted

[cwarnermm]

The product docs source code uses a few different types of syntax for table-based content which applies inconsistent default CSS look & feel across the site.

Examples:

• https://docs.mattermost.com/about/faq-product.html#what-features-are-available-on-different-mattermost-clients
• https://docs.mattermost.com/configure/calls-deployment.html#modes-of-operation
• https://docs.mattermost.com/upgrade/important-upgrade-notes.html

Goal: Provide a standard way to display all table-based content site wide.

1. Investigate pros & cons of each approach.
2. Align on a single standard approach.
3. Work with UX to ensure that table formatting is sufficiently easy to scan/read, particularly in cases where tables are complex, such as the Important Upgrade Notes page.

[cwarnermm]

Network table is weirdly large

[cwarnermm]

https://pradyunsg.me/furo/reference/tables/

[Pranavram22]

looks simple I wanna work on this

[TomerPacific]

@cwarnermm - I'd like to help here, but I think that there is a need to understand if certain pages that have tables, can be converted to not having them.
What I mean by that is, say that we agree on a specific format, regardless of what that format is, some tables (like this one) make it harder to understand the data rather than making it plain.

Would you be open to discussing this? Is there a specific channel this would be best suited to be discussed? Possibly with the UX team?

[cwarnermm]

@TomerPacific - Very open to discussing further. This issue has multiple parts.

One top-of-mind issue is that our current Sphinx theme limits the amount of horizontal space available in the center pane, which results in tables longer than the maximum requiring horizontal scrolling to view (which isn't ideal for users).

Another key part of this issue is identifying which table syntax is best for both contributors maintaining the code base as well as users viewing the details in the published product docs. Each syntax approach has pros and cons.

I'm curious to hear more about your thoughts on how the product feature breakdown table format currently makes it harder to understand the details. What about the table is causing issues for you? And what would you recommend as an alternative way format, if not a table-based approach?

[TomerPacific]

@cwarnermm -

1. If you look at the table in question, you can see that it spans longer than one height of the browser. So when you scroll down, you have to "remember" what each column stands for.
2. More so, at first, there are many rows with lots of X or O which if you are not familiar with every row, might get confusing.
3. On top of that, the table itself is divided into sections, which can be hard to differentiate.
4. The table also has a horizontal scroll, which is only observed at the bottom

Those are just a couple of points.

[cwarnermm]

@TomerPacific - Those are excellent points and I completely agree that all of the issues you've listed make the content more challenging to understand.

I am very open to proposals on presenting that feature breakdown in another way that's still scannable at a glance. If this is something you're interested in taking on, please feel free to create a docs issue to refactor the content on this one docs page and submit a docs PR with your proposed updates.

While I'd like to address the table issues holistically site-wide, I can also see good value in addressing table issues on a per-page basis.

[TomerPacific]

@cwarnermm - Sounds good. Let me know what you prefer that I tackle first.

[cwarnermm]

No preference from my end, @TomerPacific! :) Whatever order works for you also works for me!

[TomerPacific]

@cwarnermm - Created #7498