ethereum-optimism · krofax · Oct 3, 2024 · Oct 2, 2024
@@ -6,10 +6,12 @@ description: This guide explains how to write technical content for Optimism Doc
 
 import { Callout } from 'nextra/components'
 
-# Docs Style Guide
+# Docs style guide
 
 This Style Guide aims to assist Optimists in writing technical content with a consistent voice, tone, and style. See the [glossary](/connect/resources/glossary) for an alphabetical listing of commonly used words, terms, and concepts used throughout the technical docs and across the OP Collective.
 
+This doc doesn't cover all questions or use-cases. Our guide is based off the [Microsoft Writing Style Guide](https://learn.microsoft.com/en-us/style-guide/welcome/). Please reference their guide for any use-case or situation we do not cover here.
+
 *   For docs-related questions or comments, create an issue in the [docs repo](https://github.com/ethereum-optimism/docs/issues).
 *   For support-related questions or comments, create an issue in the [developers repo](https://github.com/ethereum-optimism/developers/issues).
 
@@ -23,9 +25,9 @@ This Style Guide aims to assist Optimists in writing technical content with a co
 *   [Content Types](#content-types)
 *   [General Formatting](#general-formatting)
 
-## Files, Folders, and Naming Conventions
+## Files, folders, and naming conventions
 
-### Folder Structure
+### Folder structure
 
 The folder structure for the [docs.optimism.io](https://github.com/ethereum-optimism/docs) repository is organized into several high-level categories under the main `pages` folder such as `builders`, `chain`, `connect`, and `stack`.
 
@@ -41,19 +43,19 @@ In general, filenames should be as short as possible (\~2 to 4 words) and all lo
 
 **Example:** `writing-a-guide.mdx` or `run-node.mdx`
 
-### File Paths
+### File paths
 
 File paths, when mentioned **within** a docs page, should be formatted as code snippets for readability and wrapped in backticks.
 
 **Example**: `/source/docs/assets/images/`
 
-## Writing Style
+## Writing style
 
-### Voice and Tone
+### Voice and tone
 
 Write in a friendly, yet professional tone. We are upbeat, knowledgeable, and **optimistic** about the development of the Optimism Collective, which we try our best to convey in our technical documentation.
 
-### Clear and Concise Language
+### Clear and concise language
 
 *   Be consistent. Use the same terminology, voice, and tone throughout the documentation.
 *   Be concise. Focus on providing key information and avoid including superfluous information.
@@ -67,7 +69,7 @@ Write in a friendly, yet professional tone. We are upbeat, knowledgeable, and **
 
 See below for when to use title or sentence case.
 
-*   Avoid using all caps as it slows down reading comprehension. If you need to make content prominent, use **bold** rather than all caps or italics.
+*   Avoid using all caps as it slows down reading comprehension. 
 
 *   Capitalize proper nouns in sentences. <br />
     **Example**: I use Visual Studio on my local machine.
@@ -110,20 +112,20 @@ When creating content, ensure it is accessible to screen-reader users, visually
 *   Don't use images of text, code samples, or terminal output. Use actual text.
 *   Use SVG instead of PNG if available. SVGs stay sharp when users zoom in on the image.
 
-## Content Organization
+## Content organization
 
 We aim to use consistent organization that is also user-centered and accessible. This requires intentional work and planning to group technical content into sections instead of using long, dense paragraphs. This also gives readers a visual rest from a usability perspective and improves reading comprehension.
 
 *   Use structured headings (H1, H2 or #, ##) to guide readers through the technical documentation.
 *   Use numbered lists for chronological steps.
 *   Use bulleted lists to visually separate content that does not require a specific order.
-*   Format text for optimal readability (bold vs. italics). Avoid using italics in web content as it decreases readability. Use bold if you need to make content prominent but use it sparingly. For instance, **bold** is appropriate to use when referring to a specific button or page name in technical documentation.
+*   Format text for optimal readability (bold vs. italics). Avoid using italics in web content as it decreases readability. For instance, **bold** is appropriate to use when referring to a specific button or page name in technical documentation.
 *   Organize technical content to cover only one major concept or task at a time.
-    *   **General rule of thumb**: documents with > 3 levels of structured headings (H4 or ####) and/or > than 20 minutes estimated reading time (ERT) need Revisions will typically involve editing for conciseness, splitting the document into multiple pages, or both.
-    *   revisions will usually require editing for concision, breaking the document apart into multiple pages, or some combination of the two.
+    *   **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.
+    *   Revisions will usually require editing for concision, breaking the document apart into multiple pages, or some combination of the two.
 *   Organize content based on the audience's varying needs and prior knowledge. If pre-requisite knowledge is necessary to complete a task or understand a concept, then share it with users (including links to learn more), so they can easily get up to speed.
 
-### Meta Tags
+### Meta tags
 
 *   Define the meta **title**, **language**, and **description** for each page to improve SEO ranking of the docs. Place meta tags at the top of the page before the H1 tag, with 3 dashes surrounding the block of text on either side.
 
@@ -147,7 +149,7 @@ We aim to use consistent organization that is also user-centered and accessible.
   —-<br />
 </Callout>
 
-### Page Titles (H1)
+### Page titles (H1)
 
 *   Create concise page titles and format as H1. The title should be able to fit on 1-2 lines.
 *   Every page must have an H1 heading, in addition to the page title being defined in the SEO meta tags.
@@ -169,11 +171,11 @@ We aim to use consistent organization that is also user-centered and accessible.
 
 *   Use headings in a logical manner, and the site will automatically generate anchor links for H2 and H3 tags and place them in a Table of Contents (TOC) in the right column.
 
-*   Avoid H4 levels and above within guide and template pages. As stated elsewhere in this style guide, technical documents with > 3 levels of structured headings (H4 or ####) usually indicates clarity, organization, or structural issues and should be revised.
+*   Avoid H4 levels and above within guide and template pages. As stated elsewhere in this style guide, technical documents with more than 3 levels of structured headings (H4 or ####) usually indicates clarity, organization, or structural issues and should be revised.
 
 *   H4 headings are reserved (at this time) for glossary terms. This standardization will make it easier for us to extend glossary functionality across the docs in the future, such as tool tips.
 
-### Listing Prerequisites (Before You Begin)
+### Listing prerequisites (Before you begin)
 
 *   Add a "Before You Begin" section at the top of the document if there are tasks a user needs to complete before continuing with the current task, e.g. installing a module, downloading a software update, etc.
 *   Use the title "Before You Begin"and format as H2. It should follow the page overview/intro section or table of contents.
@@ -186,7 +188,7 @@ We aim to use consistent organization that is also user-centered and accessible.
 
 ### Callouts
 
-*   Use callouts to direct users to information necessary to complete a task or information of special importance. When adding a callout to a document, use sentence case and use bold text sparingly.
+*   Use callouts to direct users to information necessary to complete a task or information of special importance. When adding a callout to a document, use sentence case.
 *   Use the correct callout type based on the type of issue: a) info/general, b) warning, c) error. Our documentation platform supports 4 different callout types.
     *   The default and info callouts are used to share non-sensitive, non-breaking info with users, such as suggestions or best practices that might make the installation or deployment easier.
         <Callout type="info">
@@ -207,7 +209,7 @@ We aim to use consistent organization that is also user-centered and accessible.
         </Callout>
 *   Use callouts sparingly as too many can be confusing to readers. **As a general rule of thumb:** pages with more than 2 callouts likely needs revision and/or a discussion with an Optimism developer or product manager to ensure guide content accuracy.
 
-### Code Samples
+### Code samples
 
 *   Use code samples as often as possible to help explain concepts. Can be used in guides or tutorials, but every tutorial should have at least one code sample to be useful to developers.
 *   Any bits of code should be wrapped in backticks and use built-in syntax highlighting. Most documentation platforms automatically apply syntax highlighting when properly defined inside the code block.
@@ -231,7 +233,7 @@ console.log('hello, world')
     *   adding or showing the line numbers within the code block (easily refer to a certain code lines within the documentation)
     *   highlighting lines or strings in the code block to draw user's attention to specific areas
 
-### Images, Screenshots, & Icons
+### Images, screenshots, & icons
 
 *   Images, screenshots, and icons are stored in the `public/img` directory in the root folder.
 *   Every image and screenshot should have descriptive alt text.
@@ -280,7 +282,7 @@ clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allo
 
 Developers trust that we will lead them to sites or pages related to their reading content. In order to maintain that trust, it's important that links are transparent, up-to-date, and lead to legitimate resources.
 
-### Internal Links
+### Internal links
 
 *   Internal links are automatically generated based on the H2 and H3 title tags.
 
@@ -292,7 +294,7 @@ Developers trust that we will lead them to sites or pages related to their readi
 
 *   To link to an anchor, such as an H3 tag within a page, you need to append it to the page name preceded by `#`, like this **example**: `[any descriptive text](/chain/getting-started/overview#test-your-application)`.
 
-### Linking Across Pages
+### Linking across pages
 
 *   Use absolute or relative links when linking across pages in the site. Absolute links are cleaner and easier to work with when pages are nested, so they are the recommended option.
 
@@ -314,7 +316,7 @@ Developers trust that we will lead them to sites or pages related to their readi
 
     **Example**: For more information, see [Article Title](/builders/app-developers/bridging/standard-bridge).
 
-## Content Types
+## Content types
 
 Content types help manage technical content by defining the purpose and common structure for each file type. All content types used in these technical docs have attributes or properties, as defined below.
 
@@ -356,9 +358,9 @@ To maintain consistency, guides should include all these items:
 *   one or more visual elements (e.g., images, screenshots, illustrations, and/or code samples)
 *   next steps section: links to related tutorials, other guides, troubleshooting, etc.
 
-### Quick Starts
+### Quick starts
 
-A Quick Start Guide should be brief (thus "quick"), easy to read, and focused on helping customers get started with only the basics of your product or service. It is usually a condensed version of a longer getting started guide (or a longer tutorial), so it is not a replacement but an accompaniment or companion piece to the docs set.
+A Quick start guide should be brief (thus "quick"), easy to read, and focused on helping customers get started with only the basics of your product or service. It is usually a condensed version of a longer getting started guide (or a longer tutorial), so it is not a replacement but an accompaniment or companion piece to the docs set.
 As a rule, this content type should describe only one scenario. It's value lies in its simplicity and ability to speed up onboarding (e.g., installation, deployment, etc.) and developers' first steps, thus improving the developer experience.
 
 To maintain consistency, quick start guides should include these items:
@@ -403,6 +405,8 @@ When writing tutorials or quick starts, steps should be written in parallel styl
 
 ### FAQs
 
+Whenever possible, we should avoid using FAQs due to their lack of readability and difficulty of maintenance. 
+
 FAQs address common questions developers have/might ask about a product, feature, or service. FAQs should be written from the developer's perspective. If there are more than two steps in the answer, use a numbered list. Place FAQs onto their own separate pages, whenever possible, and link to the FAQ from within the respective guide or tutorial.
 
 To maintain consistency, FAQs should include all of these items:
@@ -433,7 +437,7 @@ The heading level for FAQs will vary based on if it's an FAQ-only doc or if FAQs
 
 Include a category heading when you need to group related FAQ content (e.g., See the Optimism Glossary for a detailed example). Category headings are optional, but helpful, for longer FAQs.
 
-### Troubleshooting Guides
+### Troubleshooting guides
 
 Troubleshooting guides list common problems a developer might encounter while using a product or service, identifies the symptoms, and offers solutions to these problems. It is important to accurately capture symptoms produced by the system or interface (e.g., error messages, unexpected page refresh/reload, spinning wheel, etc.), so developers know if their system response aligns with one of the common problems identified in the troubleshooting guide.
 
@@ -448,7 +452,7 @@ To maintain consistency, troubleshooting guides should include all of these item
 *   solution (step-by-step)
 *   next steps section: links to related tutorials, other guides, etc.
 
-### Technical Reference
+### Technical reference
 
 Technical references provide deep, theoretical knowledge of the internal workings of a system. These often come in the form of requirements or system specifications developers need to run the product efficiently, so lists and tables, such as API endpoints and error codes are commonplace.
 A technical reference page is usually quite long, so it is best practice to embed a table of contents (TOC) at the top of the page to help organize material for developers. From a usability perspective, this practice shows developers what will be covered in the reference in advance, and allows them to jump to a specific section, if desired.
@@ -463,17 +467,17 @@ To maintain consistency, technical references should include all these items:
 
 Technical references often include more links throughout the document than other content types, often linking to other technical references, guides, tutorials, glossary definitions, etc. Since the purpose of technical reference material is to educate developers on a deeper level about the topic of their choosing, this is a common and expected practice and is a good indication of a strong technical reference.
 
-## General Formatting
+## General formatting
 
 ### Fonts
 
 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.
 
-### Bullets & Unordered Lists
+### Bullets & unordered lists
 
 Please use `*` instead of `-` for items in a list. This maintains consistency across the docs.
 
-### Date & Numbers
+### Date & numbers
 
 *   Use the full month, day, year format for dates whenever possible. Do not abbreviate the month. In a form or when space is limited, use slashes in the format of month/day/year without any leading zeros.