Help Wanted: Code block formatting is inconsistent

[cwarnermm]

Code blocks in the documentation are formatted inconsistently. Some of them have a background, some of them not.

Example: Install Mattermost on Kubernetes - Mattermost documentation

Than we have these code blocks here: Install Mattermost via Docker - Mattermost documentation Which are shown without a background.

Sometimes they should have a background for the code blocks, like in Install Mattermost on Kubernetes - Mattermost documentation point 4, but the one in the helm chart seems to be off.

[cwarnermm]

On this page Important Upgrade Notes - Mattermost documentation, the SQL syntaxes are formatted quite inconsistently. Some lines of the code are written as inline code whereas others are enclosed within code blocks and yet, some others are enclosed with both of them. Some occurrences can be at the upgrade note sections of v7.9, v7.8, etc.

[chessmadridista]

Hi, may I take up this issue? It seems like a straightforward change.

[cwarnermm]

Hi, @chessmadridista! The goal of this issue is to standardize on code blocks across all pages of the docs set. How would you approach this issue to standardize the code blocks?

[chessmadridista]

We need to standardize the code blocks across the entire documentation. All code blocks will have a background to maintain uniformity and to improve readability.

I will take the following steps:

• [x] 1. Create an Excel sheet documenting which pages contain code snippets. 1.1. For each page, we will have the following columns:
• (col_1) Link: the link of the page.
• (col_2) Does it contain code snippets?: Y/N values.
• (col_3) Is everything properly formatted?: Y/N values for checking whether every code block in it is properly formatted (indentations, for example).
• (col_4) Do the code blocks have a background?: Y/N values for checking whether every code block in it has a background.
• (col_5) Are all the corrections done?: The cells will be filled with green background color to track the status of each page.
• [ ] 2. For every row marked Y for col_2 and N for col_3 or `col_4, I will make the necessary changes.
• [ ] 3. Once the changes are done, I will skim through the links to see whether every code block has a background and whether everything is properly formatted (indentations, for example).
• [ ] 4. After reviewing, I will create a PR.

As to how to add the background and do the proper formatting, I will look into the code blocks which have already have backgrounds and proper formatting and will replicate the functionality in places wherever it is needed.

[cwarnermm]

@chessmadridista - This is a great approach. As you dig further into the source code driving the code blocks, you'll find that code blocks can differ by type of code, and that not all types of code blocks have the same underlying CSS driving their look and feel. You'll want to take this into consideration in your tracking spreadsheet too.

[chessmadridista]

Thank you @cwarnermm for the feedback! I will keep that in mind while working on this issue.

Can you please assign me this issue if nobody else is working on it actively?

[chessmadridista]

Hi @cwarnermm, here is the sheet.

Please let me know if I need to add any other columns that I might have missed.

[cwarnermm]

Thanks, @chessmadridista! You may want to consider:

• a column tracking GitHub PRs for these changes too (particularly if you feel that changes will be introduced across multiple PRs over time)
• a column identifying the underlying code format syntax specified for the block. This would help identify CSS changes, common to a block, that need to be introduced to impact look & feel.

[chessmadridista]

Hi @cwarnermm, I have added the following columns as discussed.

• Col F: Current code format syntax for the code blocks.
• Col G: Updated code format syntax for the code blocks.
• Col J: PR #.

[cwarnermm]

Thanks, @chessmadridista! Similar to my feedback on https://github.com/mattermost/docs/issues/6658#issuecomment-2178795997, let's track source file name instead of page title. And perhaps we don't need column I, given that the spreadsheet is tracking granular detail already in previous columns.

If a given docs page doesn't include any code snippets, perhaps we don't include it in this spreadsheet (which eliminates the need for column B).

[chessmadridista]

Thanks, @chessmadridista! Similar to my feedback on #6658 (comment), let's track source file name instead of page title. And perhaps we don't need column I, given that the spreadsheet is tracking granular detail already in previous columns.

If a given docs page doesn't include any code snippets, perhaps we don't include it in this spreadsheet (which eliminates the need for column B).

Noted @cwarnermm, apologies for the late reply as I was away on vacation.

I have made the changes as suggested. I will start working on this now.

[chessmadridista]

@cwarnermm, I have a design question. Won't having a background for code snippets obfuscate the reading material and hamper the UX? I mean that the code snippets are already highlighted in themselves. So is there any particular pain point that we would be solving by adding the background? Or would removing the backgrounds be better?

Update: Okay, so I understand why background is needed at certain places. Some pages like this one have extra instructions for the code snippets. But my question is related to code snippets which are alone, like this one. This code snippet does not have any accompanying information like this one does, so is the background needed in this case as well?

[cwarnermm]

That's a good question, @chessmadridista. @matthewbirtch and UX Team, I'd love to hear your thoughts on this.

[matthewbirtch]

I see we have doubled-up background in a lot of places. I'm not seeing the need for it. We should avoid having two backgrounds wherever possible. It wastes space and doesn't seem to really help anything. Just keep the background on the code itself and remove the outer container's background.

So instead of this:

Do this:

[chessmadridista]

Hi @matthewbirtch, got it. Thank you for the clarification!

@cwarnermm, do you think I should proceed with the proposed changes?

[cwarnermm]

I completely agree with @matthewbirtch's input and feedback. Thanks, Matt! @chessmadridista - please implement Matt's changes as described.