Icon HelpCircleForumIcon Link

⌘K

Icon HelpCircleForumIcon Link
Style Guide

Icon LinkStyle Guide

This style guide is a set of guidelines for writing and editing documentation. It's important to follow these guidelines to ensure that our documentation is consistent and easy to read.

Icon LinkGeneral Guidelines

Icon LinkWriting

  • Use a friendly and conversational tone of voice.
  • Use an active voice (vs. a passive voice).
  • Avoid long paragraphs or sentences.
  • Always use accurate and verified information.
  • Maintain consistency in style across pages and sections.
  • Assume the reader does not have a lot of context. Keep in mind that readers have different levels of expertise.
  • Don't use click here or read this document for links. Just link the thing Icon Link in context.
  • Don’t use double negatives.

Icon LinkWords

  • Use second-person perspective (use you).
  • Use American English.
  • Use simple (but accurate) words.
  • Avoid slang, jargon, or making up new words. Everything should be easy to translate into major languages.
  • Avoid gendered words or pronouns like “his”, “her”, “manned”, etc.
  • Define acronyms and abbreviations on first usage and if they're used infrequently.
  • Use italics or bold text to emphasize a word. Avoid using all capital letters.
  • Avoid using words that indicate time like “new feature”, as it may fall out-of-date quickly.
  • Avoid the word “please” in an instruction.
  • Avoid violent words.
  • Don’t use offensive language.

Icon LinkCode

  • Use code examples whenever possible.
  • Always specify the language of a code block.
  • Avoid hard-coded examples, and instead import code examples from code that is routinely tested.
  • Use comments to define code examples to be imported instead of line numbers that may change.
  • Always wrap inline code in backticks.
  • Always use code fences when showing commands and separate commands from console outputs. The user should be able to copy and paste the entire code in the code fence.
  • Use descriptive variable names in code examples. Don’t use foo , bar , baz , etc.

Icon LinkOrganizing Information

  • Use the standard HTML heading hierarchy: The first line should be an h1 (use 1 # in markdown) and should be the only h1 on the page. The subheadings shouldn’t skip a level, e.g. h3 tags should only be inside h2 tags.
  • Organize information so that readers can skim the page and get an answer for the most common questions quickly. Use subheadings to call out important information, and use a blockquote to identify supplemental information.
  • Avoid using tables.

Icon LinkGraphics

  • Don’t create complex flow-charts (having more than 5-6 items).
  • Don't use images of text or code. Use the actual text or code in markdown format.

Icon LinkLists

  • Use numbers, number-letter combinations (1.a, etc.), or bullet points for lists. Do not use Roman numerals or letters alone.

Icon LinkGuides

If you are writing for a guide or the intro or fuel-101 sections, follow these additional guidelines:

Icon LinkComponents

To maintain accuracy and consistency, it is recommended to use the available React components within a guide whenever they apply. For example:

  • Use the CodeImport and TextImport components instead of copying and pasting code or text.
  • For images, use the Box.Centered component to center the image.
  • For content only applicable to a certain version of the docs, use the ConditionalContent component.

You can find examples for how to these components within the docs/guides/docs Icon Link folder.

For a full list of components available, see the src/components/MDXRender.tsx Icon Link component.

Icon LinkVariables

There are several variables passed into the MDX context that you can use within a guide. You can find a full list in the src/components/MDXRender.tsx Icon Link component.

You can then use these variables within a guide like so:

The faucet URL is {props.faucetUrl}

Which would render as: The faucet URL is https://faucet-beta-5.fuel.network/