feat(styleguide): improvements #1417
Open
+71
−23
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
Gusarich
added
scope: contribute
|
To fix the formatting issues:
npx remark -o --silent --silently-ignore contribute/style-guide-extended.mdx contribute/style-guide.mdx |
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
contribute/style-guide-extended.mdx
Outdated
| ##### Italics | ||
|
|
||
| - Link text **MUST NOT** be styled with bold or italics. Do not wrap links in emphasis (for example, `**[Foo](/foo)**`, `_ [Foo](/foo)_`) and do not put bold or italic markup inside the link label. When the link label is a code identifier, use inline code as the label (for example, ``[`foo_bar`](/ref/foo_bar)``). (Why: links are already visually distinct; extra emphasis adds noise and makes scanning harder.) \[HIGH] | ||
| - Italics **MAY** be used for first‑mention term emphasis or titles of publications, books, papers, or standards. Avoid using italics for recurring emphasis in procedures. (Why: minimal, conventional italics aid comprehension without competing with steps.) |
Collaborator
There was a problem hiding this comment.
conventional italics aid comprehension without competing with steps
which steps?
contribute/style-guide-extended.mdx
Outdated
|
|
||
| - performs chain‑affecting operations (e.g., resharding, pruning, halting, replay). (Why: these actions can corrupt the state, reduce availability, or cause data loss.) \[HIGH] | ||
|
|
||
| - On pages with many such steps, you **MAY** combine these into a page‑level safety summary plus short local callouts for individual commands instead of repeating full details every time. (Why: a shared summary avoids repetition while still making risks visible near each step.) |
contribute/style-guide-extended.mdx
Outdated
| ### 11.2 How to write the callout | ||
|
|
||
| A safety callout **MUST** include: (Why: readers need to know the risk, scope, recovery, and safe environment before proceeding.) \[HIGH] | ||
| A guide that contains safety‑critical steps **MUST** clearly communicate all of the following, either in a page‑level safety summary, in local callouts near each step, or in combination: (Why: readers need to know the risk, scope, recovery, and safe environment before proceeding.) \[HIGH] |
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.
closes #943