Background
Currently we're applying code formatting in inline comments sparesly and inconsistently.
In order to provide consistent and inclusive documentation with reduced cognitive load we should follow a particular style.
When comparing following different Markdown comments
- An icon at the end of the textarea element. Similar to an ::after pseudo-element.
- An icon at the end of the textarea element. Similar to an ::after pseudo-element.
- An icon at the end of the <textarea> element. Similar to an ::after pseudo-element.
The third option is the clearest and most inclusive.
Why?
Clarity of Syntax
- Markdown often supports HTML elements. Including the explicit <textarea> ensures clarity about the type of element involved.
- This is particularly helpful for users with varying levels of expertise, as the <textarea> is a recognizable HTML tag.
Inclusivity Across Accessibility Needs
- People using assistive technologies (e.g., screen readers) or those less familiar with programming terminology might not understand textarea without the angle brackets < >.
- Specifying <textarea> aligns with common documentation practices, making it universally recognizable.
Reduces Ambiguity
- Without the angle brackets, "textarea" could be misinterpreted as general text or another concept entirely, rather than a specific HTML element.
- This distinction becomes crucial in international or beginner-friendly contexts.
Goal
Agree on above and apply uniform way to markup code (and HTML elements)
Acceptance criteria
- All Codex pages have been unified to the agreed-on format