Update style guide to align with MS guide #945
Conversation
WalkthroughThe pull request introduces several modifications to the "Optimism Docs Style Guide," primarily focusing on stylistic consistency and content enhancements. Key changes include the title and header adjustments to lowercase for uniformity, the addition of new content to clarify the guide's scope, and expanded sections detailing formatting, structuring, and SEO-related meta tags. The document's organization has been improved, providing clearer instructions for users creating technical documentation. Changes
Possibly related PRs
Suggested reviewers
Thank you for using CodeRabbit. We offer it for free to the OSS community and would appreciate your support in helping us grow. If you find it useful, would you consider giving us a shout-out on your favorite social media? 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
Documentation and Community
|
✅ Deploy Preview for docs-optimism ready!
To edit notification comments on pull requests, go to your Netlify site configuration. |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Outside diff range and nitpick comments (9)
pages/connect/contribute/style-guide.mdx (9)
Line range hint
9-27: LGTM! Introduction and table of contents are well-structured.The addition of the Microsoft Writing Style Guide reference and the table of contents improves the document's usability.
Consider using title case for all entries in the table of contents for consistency with the rest of the document. For example:
- "Files, Folders, and Naming Conventions"
- "Writing Style"
- "Content Organization"
Line range hint
28-51: LGTM! Clear guidelines for file organization and naming conventions.The section provides comprehensive information about folder structure, file naming, and path conventions.
In the filename example, consider adding a brief explanation of why hyphens are used:
Example:
writing-a-guide.mdxorrun-node.mdx(use hyphens to separate words for better readability)
Line range hint
52-101: LGTM! Comprehensive writing style guidelines.The section provides clear instructions on voice, tone, language clarity, and capitalization rules with helpful examples.
Consider adding a note about capitalization in code snippets:
"In code snippets, follow the capitalization conventions of the programming language or framework being used."
Line range hint
102-114: LGTM! Comprehensive accessibility guidelines.The section provides essential information for creating accessible content, including alt-text, captions, and image usage guidelines.
Consider adding a guideline about image file size:
"Optimize images for web use to ensure fast loading times, especially for users with slower internet connections."
🧰 Tools
🪛 LanguageTool
[style] ~121-~121: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...ered lists for chronological steps. * Use bulleted lists to visually separate con...(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
[duplication] ~124-~124: Possible typo: you repeated a word
Context: ...tured headings (H4 or ####) and/or more than than 20 minutes estimated reading time (ERT)...(ENGLISH_WORD_REPEAT_RULE)
Line range hint
115-151: LGTM! Well-structured content organization guidelines.The section provides clear instructions for organizing content, including headings, lists, and meta tags.
There's a typo in one of the bullet points. Please apply this fix:
- * **General rule of thumb**: documents with more than 3 levels of structured headings (H4 or ####) and/or more than than 20 minutes estimated reading time (ERT) need revisions will typically involve editing for conciseness, splitting the document into multiple pages, or both. + * **General rule of thumb**: documents with more than 3 levels of structured headings (H4 or ####) and/or more than 20 minutes estimated reading time (ERT) will typically need revisions that involve editing for conciseness, splitting the document into multiple pages, or both.In the meta tags subsection, consider adding a note about keeping meta descriptions under 160 characters for optimal display in search engine results.
🧰 Tools
🪛 LanguageTool
[style] ~121-~121: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...ered lists for chronological steps. * Use bulleted lists to visually separate con...(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
[duplication] ~124-~124: Possible typo: you repeated a word
Context: ...tured headings (H4 or ####) and/or more than than 20 minutes estimated reading time (ERT)...(ENGLISH_WORD_REPEAT_RULE)
Line range hint
152-177: LGTM! Clear guidelines for page titles and headings.The subsections provide comprehensive instructions for creating and formatting page titles, headings, and table of contents.
In the guideline about avoiding H4 levels, consider adding a brief explanation:
"Avoid H4 levels and above within guide and template pages. This helps maintain a clear and easy-to-follow document structure, improving readability and navigation for users."
🧰 Tools
🪛 LanguageTool
[style] ~172-~172: Consider replacing this phrase with the adverb “logically” to avoid wordiness.
Context: ...
* Use headings in a logical manner, and the site will automatically genera...(IN_A_X_MANNER)
Line range hint
178-211: LGTM! Clear guidelines for prerequisites and callouts.The subsections provide comprehensive instructions for creating "Before You Begin" sections and using callouts effectively.
In the callout guidelines, consider adding a note about accessibility:
"Ensure that the information in callouts is also conveyed in the main text, as some screen readers may skip over callout sections."
Line range hint
212-271: LGTM! Comprehensive guidelines for code samples and images.The subsections provide clear instructions for using code samples, images, screenshots, and icons effectively.
In the image guidelines, consider adding a note about color contrast:
"When creating or selecting images and icons, ensure sufficient color contrast for better visibility and accessibility, especially for users with visual impairments."
Line range hint
272-530: LGTM! Comprehensive guidelines for various content elements and types.The sections provide clear instructions for videos, links, content types, and general formatting, covering a wide range of scenarios and best practices.
In the FAQ guidelines, consider adding a note about keeping answers concise:
"Strive to keep FAQ answers brief and to the point. If an answer requires extensive explanation, consider creating a separate guide or article and linking to it from the FAQ."
In the font guideline, there's a potential issue with the wording. Please apply this fix:
-Fonts in Optimism technical documentation are setup to follow brand guidelines established by marketing (e.g., heading fonts are different than body or paragraph font). Please do not change them. +Fonts in Optimism technical documentation are set up to follow brand guidelines established by marketing (e.g., heading fonts are different from body or paragraph font). Please do not change them.This change corrects the use of "setup" to "set up" and replaces "different than" with "different from" for better grammatical accuracy.
🧰 Tools
🪛 LanguageTool
[grammar] ~474-~474: Make sure that the noun ‘setup’ is correct. Did you mean the past participle “set up”?
Context: ...in Optimism technical documentation are setup to follow brand guidelines established ...(BE_VB_OR_NN)
[style] ~474-~474: Did you mean ‘different from’? ‘Different than’ is often considered colloquial style.
Context: ...ting (e.g., heading fonts are different than body or paragraph font). Please do not ...(DIFFERENT_THAN)
📜 Review details
Configuration used: .coderabbit.yaml
Review profile: CHILL
📒 Files selected for processing (1)
- pages/connect/contribute/style-guide.mdx (18 hunks)
🧰 Additional context used
📓 Path-based instructions (1)
pages/connect/contribute/style-guide.mdx (1)
Pattern
**/*.mdx: "ALWAYS review Markdown content THOROUGHLY with the following criteria:
- Use proper nouns in place of personal pronouns like 'We' and 'Our' to maintain consistency in communal documentation.
- Avoid gender-specific language and use the imperative form.
- Monitor capitalization for emphasis. Use bold for prominence instead of all caps or italics.
- Ensure proper nouns are capitalized in sentences.
- Apply the Oxford comma.
- Use proper title case for headers, buttons, tab names, page names, and links. Sentence case should be used for body content and short phrases, even in links.
- Use correct spelling and grammar at all times (IMPORTANT).
"
🪛 LanguageTool
pages/connect/contribute/style-guide.mdx
[style] ~121-~121: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...ered lists for chronological steps. * Use bulleted lists to visually separate con...(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
[duplication] ~124-~124: Possible typo: you repeated a word
Context: ...tured headings (H4 or ####) and/or more than than 20 minutes estimated reading time (ERT)...(ENGLISH_WORD_REPEAT_RULE)
[grammar] ~474-~474: Make sure that the noun ‘setup’ is correct. Did you mean the past participle “set up”?
Context: ...in Optimism technical documentation are setup to follow brand guidelines established ...(BE_VB_OR_NN)
[style] ~474-~474: Did you mean ‘different from’? ‘Different than’ is often considered colloquial style.
Context: ...ting (e.g., heading fonts are different than body or paragraph font). Please do not ...(DIFFERENT_THAN)
🔇 Additional comments (1)
pages/connect/contribute/style-guide.mdx (1)
Line range hint
1-8: LGTM! Title and meta tags are well-formatted.The changes to the title and the inclusion of meta tags align with the style guide recommendations and SEO best practices.
Modernizes our style guide to align with MS as much as possible.