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