Help Wanted: Config setting notes content forces horizontal scroll

[cwarnermm]

Current

Mattermost configuration settings documentation that contains note content that exceeds the width of available center pane forces docs visitors to scroll horizontally to read the content.

Example: https://docs.mattermost.com/configure/plugins-configuration-settings.html#ice-host-override

The horizontal scroll bar is displayed because of length of the note text.

Desired

Eliminate horizontal scroll bars for all impacted configuration settings documentation.

Effort

1. Identify all Mattermost configuration settings that currently feature a horizontal scroll bar.
2. Move the note text out of the configuration setting table.
3. Format the moved note text as a standard note callout using ..note:: located directly after a given table. See https://github.com/mattermost/docs/blob/master/source/collaborate/collaborate-within-channels.rst for an example of the source code format for notes.
4. Deliver all changes in a single docs PR against this GitHub repository.

Reach out here on this issue if you have any questions, concerns, or encounter any blockers.

[guruprasath-v]

Hello I've found it, May i solve this?

[cwarnermm]

I'd welcome your help with this, @guruprasath-v!

[guruprasath-v]

@cwarnermm Should i remove every note out of the table or only those scrolling horizontally?

[cwarnermm]

Great question, @guruprasath-v! Please prioritize the ones that cause the horizontal scrolling.

[guruprasath-v]

The problem here is: Scrolling happens relative to responsiveness
some note content are not scrolling when they responsive to lap screen, but they scrolling when they shrink to Mob devices

[cwarnermm]

That's a great point, @guruprasath-v. Given the fact that scrolling is relative to display real estate, what's your recommendation for moving forward on this issue? I think I'm hearing that all notes should be taken out of tables. Would you agree?

[guruprasath-v]

@cwarnermm See here i have removed "Note" content out of the table, even though horrizontal space occuring

[cwarnermm]

Interesting! It's not necessarily the note text that's causing the table scroll, but potentially the code-formatted text that may be forcing a maximum table width beyond ~40 characters. What's interesting is that code-formatted text also wraps to the next line.

I have a theory for this example: If we shorten the config.json code-formatted text, the horizontal scroll will go away. Open to giving the following a try?

config.json setting:

PluginSettings
   Plugins
      com.mattermost.calls
         turncredentialsexpirationminutes

@streamer45 - If we reformatted the config.json to shorten exceptionally long code-formatted text lines as I propose above (modelled after the config.json file), any concerns about the readability or clarity of doing so for an admin?

[streamer45]

@cwarnermm It makes sense to me in terms of clarity. The main advantage I see with the dotted notation is that it resembles what an admin could use to get/set through mmctl, e.g.:

mmctl --local config get PluginSettings.Plugins.com.mattermost.calls

That said, for plugins specifically, that's not very consistent, as fields need to be pre-existing in the file for that to work.

[cwarnermm]

I agree that dotted notation is preferred; however, given the inconsistencies across plugins and the horizontal scroll result in docs, reformatting feels like a reasonable compromise.

[guruprasath-v]

@streamer45 @cwarnermm After a long search, I was only able to split those properties into new lines. However, the issue is that when copying, the copied text includes line breaks. I tried several methods, but this one worked slightly better than others.
I've attached a code image for your reference.

[cwarnermm]

@guruprasath-v - After spending some time in the code, I completely agree with you that this is a challenging resolution to identify. The center text pane has a finite width, and content that extends beyond that limit, like code blocks and inline code-formatted text, introduces an undesired horizontal scroll result.

I've attempted another possible way forward, subject to @streamer45's feedback:

^ @streamer45 I recognize that the formatting for the config.json setting isn't ideal; however, do you feel it's clear and easy to understand to technical audiences, as formatted & documented?

@guruprasath-v - here's a screenshot of VSCode showing you source:

[streamer45]

Yes, looks good to me @cwarnermm , thanks!

[guruprasath-v]

Okay @cwarnermm @streamer45, I'll try to eliminate all horizontal bars by taking notes content out of the table and adjusting the alignment in the config.json.

[cwarnermm]

Thank you, @guruprasath-v!!!

[guruprasath-v]

@cwarnermm Sorry for the repeated interruptions, but I need some clarity on this. Although I followed the instructions and managed to remove most of the horizontal scrollbars, there's still a horizontal bar being caused by the "link". The link is creating the problem, how can we shrink it? Is there a way to replace it with a shorter, clickable link?

[cwarnermm]

@guruprasath-v - I'm not seeing this issue via production. Long code-formatted text lines appear to wrap as expected:

Do you have a PR I can review?

[cwarnermm]

@guruprasath-v - Do you have a docs PR I can review for this issue?

[guruprasath-v]

@cwarnermm Mam, I'm working on it and need a couple more days to prepare the PR. Please allow some additional time.

[cwarnermm]

Thanks, @guruprasath-v! Please take whatever time you need.

[guruprasath-v]

Hi @cwarnermm, I have completed the task and am working on raising a PR. I'm currently stuck on inserting the ticket. Could you please guide me on how to raise the PR?

[cwarnermm]

Hi @guruprasath-v - Take a look at this video and let me know what questions you have about getting started.

[guruprasath-v]

I've raised PR @cwarnermm