Documentation Writing Guide

Write clear, helpful documentation that serves all OpenScan.AI users.

This guide covers how to contribute to OpenScan.AI documentation, including style guidelines, structure, and best practices.

Where docs live

These docs are an Astro site. Content lives in src/content/Docs as Markdown (.md) and MDX (.mdx) files; routes mirror file paths:

src/content/Docs/developers/guides/index.md  →  /docs/developers/guides

Set up the site locally with the Frontend & Docs Setup guide.

Frontmatter

Every page starts with frontmatter. Keep all existing keys when editing a page:

---
categories: ["Developers"]
tags: ["Guides", "Tutorials"]
weight: 3
title: "Developer Guides"
linkTitle: "Guides"
description: "Step-by-step tutorials for building on OpenScan.AI"
---
  • title — the page heading and browser title.
  • linkTitle — the shorter sidebar label.
  • description — used for search and link previews; one sentence, present tense.
  • weight — ordering within the sidebar section.
  • Never remove a key you don’t understand; ask in the PR instead.

Structure of a good page

  1. One-sentence summary (bolded) — what the reader will accomplish.
  2. Prerequisites — accounts, keys, tools, prior pages.
  3. Steps or reference content — the meat.
  4. Verification — how the reader confirms it worked.
  5. Next steps — links onward into related docs.

Heading rules: the title is the only h1; sections start at ##, subsections at ###. Don’t skip levels.

Style guidelines

  • Be direct. “Run mix test” not “You might want to consider running the test suite.”
  • Present tense, second person for guides; neutral voice for reference pages.
  • One idea per sentence. If a sentence has three clauses, it’s two sentences.
  • Define acronyms on first use outside of universally known ones (API, URL).
  • American English, sentence case for headings.

Code examples

Code examples are the most valuable — and most broken — part of any docs site. Rules:

  • Verify every example. Run it against xdcscan.io or a local instance before committing. Untested examples are worse than no examples.
  • Complete, not fragmentary. Show imports, variables, and the call — a reader should be able to paste the block into a file and run it.
  • Real base URLs. Use https://xdcscan.io/api/v2, never placeholder domains.
  • Label placeholders clearly. YOUR_API_KEY, 0x1234..., and similar stand out as values to replace.
  • Prefer curl and fetch for API examples — no dependency assumptions.

MDX pages

.mdx files can embed components. Rules that keep the build green:

  • Keep imports at the top, immediately after frontmatter.
  • If you remove every usage of a component, remove its import — broken imports fail the build.
  • Inside JSX props, avoid unescaped backticks and ${ in template literals.
  • Escape stray < and { in prose (or wrap them in inline code).
  • Internal links use absolute paths that match real files: /docs/api-documentation/rest-api, /docs/developers/guides.
  • Check links resolve by running npm run build — broken content collection paths fail the build.
  • External links: prefer the canonical destination (e.g. https://xdcscan.io/api-docs for API docs, https://github.com/OpenScanAI for source).

Images and assets

  • Store images next to the page (./assets/diagram.png) or in public/ for shared assets.
  • Always include meaningful alt text.
  • Keep screenshots current — a stale UI screenshot is a bug. Recapture when the UI changes.

Review checklist

Before opening a docs PR:

  • npx prettier . --write on touched files
  • npm run astro -- check passes
  • npm run build passes
  • Every code example was run
  • Every internal link resolves
  • No orphaned references to removed pages or features

Tone reference

Good documentation sounds like a colleague pairing with you: direct, specific, and honest about limitations. If a feature is experimental, say so. If an endpoint is slow, say what to do instead. Users trust docs that tell them the truth.

Edit page on github
Pull Request Process Getting Started