Skip to main content
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.
  • sidebarTitle: 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
sidebarTitle: Omnichain Application (OApp)
description: A LayerZero OApp is a crosschain 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.

​
Mintlify-Specific Styling Guide

Our documentation is hosted on Mintlify. The following guidelines ensure consistency and accessibility.

​
Markdown

  • MDX Format: We use Mintlify with MDX, which supports standard Markdown and React components. Follow standard Markdown conventions.
  • Extended Syntax: Use extended Markdown features as supported by Mintlify. See the official Mintlify 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 from the snippets/ directory using paths like /snippets/ComponentName.jsx.
  • 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

Mintlify supports several types of callout components:
  • Info: Additional relevant information.
  • Tip: Recommendations or best practices.
  • Caution: Points requiring careful attention.
  • Warning: Information about potentially dangerous actions.
Usage Examples:
This is a note admonition providing extra context.
This offers opinionated recommendations or best practices.
This warns users of potential issues that can arise.
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. Mintlify provides built-in Tab components: 
<Tabs>
  <Tab title="Solidity">
    Content relevant to Solidity.
  </Tab>
  <Tab title="Solana">
    Content relevant to Solana.
  </Tab>
</Tabs>

​
Images and Assets

  • Image placement: Store image files in the images/ directory at the root of the repository, organized by content type.
  • Referencing images: Use paths from the root (e.g., ![LayerZero Diagram](/images/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.