> ## Documentation Index
> Fetch the complete documentation index at: https://docs.layerzero.network/llms.txt
> Use this file to discover all available pages before exploring further.

# LayerZero Documentation Style Guidelines

> Documentation style guidelines for LayerZero contributors. Writing standards for Solidity, Solana, and Aptos Move blockchain developer docs and guides.

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](https://developers.google.com/style) and the [Red Hat Technical Writing Style Guide](https://redhat-documentation.github.io/supplementary-style-guide/#_about_this_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.
  * *Example:* “Refer to our [LayerZero Devtools Example Repository](https://github.com/LayerZero-Labs/devtools/) for more comprehensive 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:*

```yaml wrap theme={null}
---
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](https://github.com/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](https://mintlify.com/docs) 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.

### Links and Assets

* **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:*

<Note>
  This is a note admonition providing extra context.
</Note>

<Tip>
  This offers opinionated recommendations or best practices.
</Tip>

<Warning>
  This warns users of potential issues that can arise.
</Warning>

<Danger>
  This signals danger for critical issues.
</Danger>

*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:

```jsx wrap theme={null}
<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)`).

## Related Resources

* [Microsoft Writing Style Guide](https://docs.microsoft.com/en-us/style-guide/)
* [Google Developer Documentation Style Guide](https://developers.google.com/style)
* [Red Hat Technical Writing Style Guide](https://redhat-documentation.github.io/supplementary-style-guide/#_about_this_guide)
* [Coinbase Solidity Style Guide](https://github.com/coinbase/solidity-style-guide)

***

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