Improve formatting of "Moderator Instructions" post #343
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
per1234
added
type: enhancement
A common convention in technical writing is the "admonition", which adds supplemental information to the surrounding normal prose. These "admonitions" typically have a standardized styling that differentiates them from the rest of the prose in a visually prominent manner. This often includes putting a "box" around the text (either a border or a background color). Markdown doesn't have a dedicated admonition capability, but a standardized admonition style can be created using the general purpose markup. I have settled on the use of a leading and trailing horizontal rule (markup: `---`) to create something like a "box" around the admonition text.
Technical writing such as the "Moderator Instructions" asset post is often littered with non-prose text such as references to: - UI elements - navigation items - product names The reader may have difficulty understanding when text is prose vs a reference to one of these items. For this reason, readability is improved by formatting the text so that there is a clear visual difference between the standard prose text and the non-prose items. This can be accomplished by making these types of non-prose text bold. That formatting convention was already employed in the document, but was missing in some places. The formatting is hereby done consistently throughout the document.
Technical writing such as the "Moderator Instructions" asset post is often littered with non-prose text such as references to: - UI elements - navigation items - product names The reader may have difficulty understanding when text is prose vs a reference to one of these items. For this reason, readability is improved by formatting the text so that there is a clear visual difference between the standard prose text and the non-prose items. One of the formatting techniques that can be employed to accomplish this is quoting these types of non-prose text. Since the primary technique is bolding the text, quoting is used selectively in cases where additional visual differentiation is useful. That formatting convention was already employed in the document, but was missing in some places. The formatting is hereby done consistently throughout the document.
Technical writing such as the "Moderator Instructions" asset post is often littered with non-prose text such as references to: - UI elements - navigation items - product names The reader may have difficulty understanding when text is prose vs a reference to one of these items. For this reason, readability is improved by formatting the text so that there is a clear visual difference between the standard prose text and the non-prose items. This is done by employing several formatting techniques: - Bolding - Quoting Since the goal is only to emphasize the non-prose references, the quotes should not be bolded, so the nesting of the formatting markup must be done in the correct order. Some of the formatting was previously nested in the incorrect order, which resulted in inconsistent formatting and harmed readability.
HTML kbd tags are used to create graphical representations of the forum user interface buttons in the "Moderator Instructions" asset post. The visual appearance of the rendered content is enhanced by bolding text in the tags. The nesting of the markup can generally be in either order. However, nesting the bolding markup inside the kbd tags gives more flexibility by allowing text to be selectively bolded. For example, some graphical characters are clearer or faithful to the UI when not bolded. So the standardized style is to nest the bolding markup inside the kbd tags. Some of the markup did not comply with this standardized style.
…tions" The "Moderator Instructions" asset post consists largely of instructions in the form of ordered lists. The first line of the step should contain only the essential information. Supplemental information must be placed on subsequent lines so that it can easily be skipped over by those who are already knowledgeable on the subject.
…tor Instructions" One of the elements used in the content of the "Moderator Instructions" asset post is "admonitions". These contain information related to the surrounding content, formatted in a manner that makes them visually distinctive. "Admonitions" fall into three general categories: - Supplements: Additional information to help the reader to understand more about the subject - Notices: Important information the reader should be aware of - Warnings: Something bad can happen if an instruction is not performed correctly In order to provide a clear visual indication of the type of an admonition, it is prefixed by a standardized symbolic character.
The "Moderator Instructions" asset post frequently refers to elements of the the forum user interface. That interface makes heavy use of purely graphical elements in addition to text. Where possible, representations of those graphics are used in the UI element references. Previously, these mostly consisted of the colon bracketed emoji markup supported by the forum's post renderer. This markup is an extension rather than standard part of the Markdown markup language so the support and rendering of the markup may vary from one tool or platform to another. For example, the VS Code Markdown preview does not support the markup, so the emojis are not rendered at all for contributors using that tool during the development of the asset. This situation is improved by replacing the non-standard markup with the equivalent character. In addition to making the content more universally comprehensible, this also provides slightly better control over these graphical characters (the rendering of the emoji tends to change more dramatically over time).
The "Moderator Instructions" asset contains instructions for filling in text fields. The most appropriate markup for this content is the backticks (code span) markup.
The "Moderator Instructions" asset post contains a set of instructions in the form of an ordered list with each step illustrated using a screenshot of the forum UI. In order to improve readability, a blank line was inserted between the text of the step and the accompanying screenshot. This can be accomplished in two ways: - A `<br />` HTML tag - A blank line (Markdown paragraph markup) For some reason, both of the above were used. Although the redundant markup didn't affect the rendered content, it adds unnecessary complexity to the source markup, making it less friendly to contributors and more difficult to maintain. For this reason, the redundant markup is removed. Since it is the more intuitive of the two, the blank line markup was retained.
per1234
force-pushed
the
format-moderator-instructions
branch
from
d7d0359 to
43a4a67
Compare
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Various adjustments to the formatting of the "Moderator Instructions" asset post to improve readability and maintainability.
The changes are separated categorically in the individual commits of the pull request:
https://github.com/arduino/forum-assets/pull/343/commits
See the individual commit messages for detailed explanations of the changes.
Preview the updated content here:
https://github.com/per1234/forum-assets/blob/format-moderator-instructions/content/categories/staff/moderation/_topics/moderator-instructions/1.md#readme
Related discussion:
https://forum.arduino.cc/t/discussion-re-moderator-documentation-content/852461 (private)