Writing Guide

Writing Style

This applies to all documentation, code comments, and design documents.

Use clear, simple language. Write short, impactful sentences. Use active voice. Focus on practical, actionable information.

Address the reader directly with "you" and "your". Support claims with data and examples when possible.

Avoid these constructions:

• Em dashes (use commas or periods)
• "Not only this, but also this"
• Metaphors and cliches
• Generalizations
• Setup language like "in conclusion"
• Unnecessary adjectives and adverbs
• Emojis, hashtags, markdown formatting in prose

Avoid these words: comprehensive, delve, utilize, harness, realm, tapestry, unlock, revolutionary, groundbreaking, remarkable, pivotal This includes all simmilar verbage, clean fact-based technical explainations only.

Rules

• Do NOT over-use bullet points
• Less code examples the better, prefer english with short examples
• You are as much documenting software as you are teaching it, a balence of explainations and examples is important
• Always open with a powerful introduction
• Prefer short document titles that match the sidebar
• Do not include ASCII diagrams or Mermaid diagrams.
• Opening paragraph should target 3-4 lines.
• Documentation is NOT for designing future features, other than a mention or note, full design implementations should be migrated to .tasks
• This is MDX meaning you can not write the less-than character without escaping it.

Usage of custom MDX components

Use callouts when needed, do not over-use but they are nice to see!

• <Note>This adds a note in the content</Note>
• <Warning>This raises a warning to watch out for</Warning>
• <Info>This draws attention to important information</Info>
• <Tip>This suggests a helpful tip</Tip>
• <Danger>This is a danger callout</Danger>

Code Snippets

Use code snippets sparingly to illustrate key concepts or demonstrate specific tasks:

• When to Use: Include snippets only when they clarify a concept better than prose or show a critical implementation detail.
• Length: Keep snippets short (under 10 lines when possible). Use comments to explain complex logic.
• Formatting: Use markdown code blocks with the appropriate language tag (e.g., ```python). Ensure snippets are complete and executable.
• Context: Introduce each snippet with a sentence explaining its purpose (e.g., "This code configures the API client").
• Testing: Verify all snippets work as intended in the specified environment. Include version numbers if relevant (e.g., "Tested with Python 3.9").

Example:

let library = core.libraries
    .create_library("Jeff's Library", None)
    .await?;

Code Groups when showing multiple languages

• <CodeGroup> rust swift typescript </CodeGroup>

Always use expandable for long code blocks

pub struct Sidecar {
    pub id: i32,
    pub content_uuid: Uuid,           // FK to ContentIdentity

    // Classification
    pub kind: String,                 // "thumbnail" | "preview" | "metadata"
    pub variant: String,              // Size/quality variant
    pub format: String,               // File format

    // Storage
    pub rel_path: String,             // Relative path to sidecar
    pub source_entry_id: Option<i32>, // Reference to existing file

    // Metadata
    pub size: i64,
    pub checksum: Option<String>,
    pub status: String,               // "pending" | "processing" | "ready" | "error"
    pub version: i32,

    pub created_at: DateTime<Utc>,
    pub updated_at: DateTime<Utc>,
}

Set parameters for API or SDK references

Customize the right panel

You can use the <Panel> component to customize the right side panel of a page with any components that you want. If a page has a <Panel> component, any RequestExample and ResponseExample components must be inside <Panel>. The components in a <Panel> will replace a page’s table of contents.

Show steps for sequential flows, only is needed

Tooltips

Use tooltips to provide additional context or definitions when a user hovers over a string of text. Tooltips can include optional call-to-action links. Example: API documentation helps developers understand how to integrate with your service.

<Tooltip tip="Application Programming Interface: a set of protocols for software applications to communicate." cta="Read our API guide" href="/api-reference"

API

Your final documentation should:

• Explain the concepts clearly
• Include relevant code examples where they add value
• Use bullet points judiciously where they help organize information
• Maintain a good flow between teaching and documenting
• Utilize our MDX helper components