Skip to main content

LayerZero Documentation Style Guidelines

Our documentation aims to provide a consistent, high-quality experience tailored to LayerZero’s unique development ecosystem, including Solidity, Solana, and Aptos Move.

Inspiration: We draw from resources like the Google Developer Documentation and the Red Hat Technical Writing Style Guide, while tailoring guidelines for our blockchain languages.

Location​

In addition to guidance on how to write, this guide also explains where to write:

  • Content placement:
    • Non–VM-specific topics should live under a generic section (e.g., Home/Concepts).
    • VM-specific developer pages should reference these generic pages for foundational content and add only VM-specific notes.
    • This approach prevents the expansion of non–VM information on VM-specific pages.

Voice and Tone​

  • Friendly and conversational:
    Write clearly and directly, as if explaining complex concepts to a friend.

  • Concise and direct:
    Present key information immediately. Steps and options should be obvious and easy to follow.

  • Human but professional:
    Remain personable and respectful. Use everyday language (including contractions) without resorting to slang or overly formal expressions.

  • Inclusive:
    Address a diverse, global audience by avoiding cultural idioms and ensuring clarity for non–native English speakers.

Writing Style and Clarity​

  • Simplicity:
    Use short, simple sentences. Break complex ideas into layered explanations so readers can focus on what matters most.

  • Directness:
    Assume technical familiarity but clarify as needed. When explaining Solidity, Solana, or Move concepts, balance technical accuracy with approachability.

  • Technical terms and buzzwords:
    Define necessary technical terms clearly. Avoid overusing buzzwords, jargon, or acronyms—if a term is essential, include a brief definition or link to a glossary.

  • Terminology management:
    Maintain a glossary for key terms. Guidelines for glossary management should include:

    • Regularly updating definitions based on latest changes.
    • Ensuring consistency in usage across documentation.
    • Cross-referencing glossary entries within the content.

What to Avoid​

To maintain clarity and consistency, steer clear of:

  • Repetition:
    Avoid mentioning similar guidelines in multiple sections. For example, advice on avoiding formal language and excessive jargon should be consolidated.

  • Placeholder phrases:
    Do not use phrases like “please note” or “at this time” unless they add necessary context.

  • Verbose or redundant explanations:
    Keep content succinct and to the point.

  • Stereotypes and biased language:
    Use diverse examples and avoid outdated or biased terminology.

  • Excessive informality:
    Limit exclamation marks and overly casual language.

Writing Inclusively​

  • Global audience:
    Write clearly and simply to support non–native English speakers.

    • Example of Good: “Use short sentences to make ideas easier to follow.”
    • Example of Not Acceptable: “Don’t be too flamboyant in your linguistic implementation, or verbose in your verbal assessments, such that the language described no longer adequately explains anything relevant or remotely useful.”

  • Lists and tables:
    Use lists or tables to organize complex information for better readability.

  • Sentence-style capitalization:
    Use standard sentence-style capitalization for bullet points and subheadings (e.g., “global audience”, “lists and tables”) except for section titles, which use title-style capitalization.

Numbers and Capitalization​

  • Numbers:
    Spell out numbers zero to nine. Use numerals for negative numbers, percentages, decimals, and measurements.

  • Capitalization:

    • Use title-style for top-level titles.
    • Use sentence-style for all other headings and text.
    • Avoid using all uppercase for emphasis.

Code Examples and Repository References​

  • Self-contained code examples:
    Ensure that every snippet is clear, concise, and includes a brief explanation.

    • What's Good: A short code snippet with style appropriate comments explaining each step.
    • What's Not Acceptable: Long, unannotated blocks of code.

  • Repository of examples:
    Link to the official repository or sample apps where readers can find additional, vetted examples.

Frontmatter Requirements​

Every documentation page must begin with frontmatter. Although many variables are optional, we require the following to ensure consistency:

  • title: The main title of the page.
  • sidebar_label: The label that appears in the sidebar (defaults to the page title if not set).
  • description: A brief description for search engine results and embedding.

Example Frontmatter:

---
title: LayerZero V2 OApp Quickstart
sidebar_label: Omnichain Application (OApp)
description: A LayerZero OApp is a cross-chain contract standard.
---

Code and API References​

  • Code formatting:
    Render code blocks, functions, parameters, and literal values using code style (e.g., using backticks).

  • API descriptions:
    Begin descriptions with an active verb (e.g., “Creates a new contract instance” or “Checks whether…”).

  • Parameter and return descriptions:
    Keep them brief and technical; note prerequisites, side effects, or possible errors.

Writing API References​

For each API, provide:

  • Complete reference:
    Document every class, function, method, event, and property with a brief, descriptive sentence.

  • Examples:
    Supply short code snippets (25–50 lines) that demonstrate usage.

    • What's Good: A concise snippet with inline comments.
    • What's Not Acceptable: A lengthy, uncommented example.

  • Consistent formatting:
    Maintain uniform code styling across examples. Use backticks for parameters and code style for function names.

Deprecations​

When marking functions, contracts, or modules as deprecated:

  • Clear notice:
    State the deprecation status, the version when it occurred (e.g., “Feb 26, 2025: Launched v1.0…”), and recommend alternatives.

  • Guidance:
    Provide clear instructions on how to transition to new implementations.

Specifics for Solidity, Solana, and Move​

Solidity​

  • Code examples:
    Use self-contained examples demonstrating contract deployment, event handling, and security practices. Refer to the Coinbase Solidity Style Guide for further details.

  • Best practices:
    Emphasize gas optimization, robust error handling, and security standards.

  • Terminology:
    Define blockchain-specific terms (e.g., “reentrancy”, “fallback functions”) clearly.

Solana​

  • Rust and C-like code:
    Ensure examples use proper Rust syntax highlighting. Explain concepts such as accounts, program-derived addresses, and transaction semantics.

  • Performance and security:
    Highlight key security patterns and performance considerations.

  • Integration examples:
    Provide clear examples for interacting with Solana’s JSON RPC API and building client-side applications.

Aptos Move​

  • Language specifics:
    Document resource types, module structuring, and transaction scripts.

  • Usage guidelines:
    Provide best practices for writing secure and efficient Move code, especially around resource management.

  • Code comments:
    Encourage inline comments that explain design decisions, especially for beginners.

Docusaurus-Specific Styling Guide​

Since our documentation is hosted on a Docusaurus-powered site, the following guidelines ensure consistency and accessibility.

Markdown​

  • Markdown:
    We use Docusaurus v2 with MDX, which supports standard Markdown and React components. Follow standard Markdown conventions.

  • Extended Syntax:
    Use extended Markdown features as supported by Docusaurus. See the official Docusaurus documentation for details.

Headers​

  • H1:
    Do not use; the page title is rendered as H1 automatically.

  • H2:
    Use for primary sections, which also affect SEO.

  • H3:
    Use for subsections that appear in the table of contents.

  • H4 and beyond:
    Use for further subdivisions; ensure logical nesting under previous headers.

Content and Line Breaks​

  • Line length:
    Keep lines to fewer than 120 characters for readability in source files.

  • Paragraphs:
    Separate paragraphs with an empty line. Use <br/> for soft line breaks.

  • Tables:
    In table cells, use <br/> for line breaks.

  • Relative links:
    Use relative links for referring to other pages or assets within the documentation.

  • Updating references:
    Update all relative links if files or components are moved.

Components and Code​

  • React components:
    Import reusable components (e.g., Tabs, Hotkeys) using absolute paths from the site’s root (e.g., @site).

  • Inline code:
    Wrap short snippets in backticks (e.g., `ComponentName`).

  • Code blocks:
    Use fenced code blocks with language specifiers for syntax highlighting. Add titles if needed for context.

Admonitions​

Docusaurus supports four types of admonitions:

  • Info: Additional relevant information.
  • Tip: Recommendations or best practices.
  • Caution: Points requiring careful attention.
  • Warning: Information about potentially dangerous actions.

Usage Examples:

info

This is a note admonition providing extra context.

tip

This offers opinionated recommendations or best practices.

caution

This warns users of potential issues that can arise.

danger

This signals danger for critical issues.

Guidance:

  • Use Tip for recommended practices, Caution when highlighting possible pitfalls, and Warning for critical issues.

Tabs​

Tabs help present context-specific content. Use Docusaurus Tabs and TabItem components as shown:

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

<Tabs groupId='example'>
  <TabItem value='solidity' label='Solidity' default>
    Content relevant to Solidity.
  </TabItem>
  <TabItem value='solana' label='Solana'>
    Content relevant to Solana.
  </TabItem>
</Tabs>;

Images and Assets​

  • Image placement:
    Store image files in docs/static, organized by content type.

  • Referencing images:
    Use relative paths (e.g., ![LayerZero Diagram](/docs/static/img/layerzero-diagram.png)).

By following these guidelines, our documentation will remain clear, concise, and inclusive—empowering our developer community while ensuring consistency across all LayerZero materials.