Help Wanted: Note Consistency and Standardization

[cwarnermm]

• Review current usage of callouts including Note, Important, Tip, and Warning used throughout the product documentation set.
• Identify key standardization efforts required for these callouts based on current usage.
• Identify all cases where these callouts deviate from the standard due to the source file being in markdown (MD) format.

Examples of standardization include:

• Whether there's a line break between the callout and following content. This is inconsistently applied throughout the docs.
• Tone and language used for each type of callout - what constitutes a warning, tip, note, or important information.

[davidylee]

Hi @cwarnermm , I'm interested in learning more about what exactly is needed here so I could work on it? Thanks!

[cwarnermm]

Hi @davidylee! Thank you for your interest in this Mattermost documentation ticket! This ticket is all about standardizing how admonitions like Notes, Tips, Warnings, and Important are used throughout the product documentation, and identifying areas where inconsistencies need to be addressed.

Admonitions in technical documentation give the reader useful, timely, or critical information that helps them succeed with a task or operation. The Mattermost Product Documentation contains four types of notes today:

• Note: Emphasizes or supplements useful details of subject matter, such as details that only apply in special cases. For example, limitations based on specific configurations, or details that apply to specific situations or product releases.
• Tip: Suggests alternative ways through to success that may not be obvious. Tips help users understand additional benefits and/or capabilities of the product.
• Important: Communicates information that is essential to the completion of a task. Can be used to communicate "proceed carefully". Users may be able to disregard the information in a note and still complete a task, but they should not disregard an important note.
• Warning: The highest level of alert to users. Advises users of the repercussions and consequences of taking a specific action or avoiding a specific action.

The work required for this ticket consists of the following:

• Review all pages throughout the Mattermost product documentation where a Note, Tip, Warning, or Important admonition is used and add each to a spreadsheet for review. The spreadsheet should contain a tab for each admonition type, the list of admonition text for all admonition of a given type, and each tab should include both a recommendation column and a notes column for discussion. Please share that spreadsheet with us so that we can work on this collaboratively with you!
• Identify whether each admonition is being used consistently and correctly based on the definitions above.
• Identify specific admonitions that need work and propose updates.
• Identify any admonitions that are formatted incorrectly.

Having all of the admonitions in a single spreadsheet helps maintain consistency in approach, voice, and tone across all admonitions.

[BabbarRaghav]

Hi, is this issue still open and without any assignees?

I would like to solve it

[cwarnermm]

Thank you, @BabbarRaghav, for your interest in contributing to Mattermost product documentation. We welcome your help with this ticket. I've assigned it to you. Please note any questions or concerns you have about the work here in the PR.

[BabbarRaghav]

hey @cwarnermm, thank you so much for assigning me this issue. Is there any code snippet or do I have to write down solution from scratch?

[cwarnermm]

Hi @BabbarRaghav! In the Mattermost Product Documentation, the majority of source files are in RST format (reStructuredText), and those RST files typically use the standard tip or note directive already. We likely have few warnings or notes marked as important.

Any source file in this doc set that isn't in RST format will be in MD format (Markdown). These notes, tips, warnings, and notes marked as important don't yet have the standard directive applied, so they won't display the same as RST formatted files. We have a follow-on task in a future iteration to format these notes to match the rest of the site.

The primary focus of this documentation ticket is to review all note, tip, warning, and important callouts from a content perspective, rather than a display perspective, and to provide input and feedback towards existing notes, tips, warnings, or important notes that are:

• inappropriately titled as a note, tip, warning, or important note based on the content of the note itself.
• written inconsistently when compared to other notes, other tips, other warnings, and other important notes

[chessmadridista]

Hi @cwarnermm, is this issue open? Can I pick it up?

Here are the steps I would take to resolve this issue:

1. • Make a spreadsheet.

• Each type of admonition will be contained in a separate tab.
• For each type of admonition, I will do whatever is written in this comment.
• As an extra, I will also add the links wherever all the admonitions occur.
• Once I have filled up the spreadsheet, I will share it with you and any other team members for review.

2. • Once the changes are reviewed in the sheet, I will start making the relevant changes.

• Once the changes are complete in the documentation, I will submit a PR.

I am excited to start working.

[cwarnermm]

Sounds great, @chessmadridista! Looking forward to working with you on this.

[chessmadridista]

Hi @cwarnermm, can you please review the columns in this sheet?

Please let me know in case any column needs to be removed or if a column needs to be added.

[cwarnermm]

This is excellent, @chessmadridista! I recommend adding a column to track the docs PR where changes are executed.

[chessmadridista]

Thank you @cwarnermm!

I have added a column for tracking the PRs for each item in every tab.

[cwarnermm]

What are your next steps for this ticket, @chessmadridista?

[chessmadridista]

Hi @cwarnermm, I will take the following steps:

1. • I will check whether the line formatting, as mentioned in the issue description, is uniform across all sections.
2. • I will tackle each type of section and standardize the language of the content wherever necessary for readability and uniformity. I will note down the changes in the spreadsheet first before making the modifications in the codebase.
3. • I then plan to make make multiple pull requests depicting small changes and will update the sheet accordingly as the requests get merged. I will do this until all the changes are complete. However, I would be happy to take help if someone is willing to contribute to this issue alongside me.
4. • After #1to #3 are completed, I will notify you here.

[cwarnermm]

This sounds like a great plan, @chessmadridista!! Thank you!

[cwarnermm]

Are you actively working on this issue, @chessmadridista?

[chessmadridista]

@cwarnermm not right now. I am working on the code background thing. I plan to take this up once that one is done.