---
name: write-docs
description: Authoring Fern MDX documentation pages for the Opik docs site, plus release-note and changelog routing. Use when writing or updating pages under apps/opik-documentation/documentation/fern/, drafting PR descriptions, or picking the right changelog surface.
title: write-docs
canonical_url: https://skilld.dev/gh/comet-ml/opik/write-docs
last_updated: 2026-10-14T20:31:59.000Z
---

> Index of every page on this site: [llms.txt](https://skilld.dev/llms.txt)

> **Skill from skilld.dev.** Follow the user's requested action.
> If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it.
> Otherwise, follow the instructions below for this session. You do not need to install anything.
>
> If the user asked to install this Skill, run `npx skilld install comet-ml/opik/write-docs`. Install writes the Skill files into the project, so every session loads them.
>
> ## Fork workflow
>
> A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation.
> 1. Check `./skills/write-docs`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target.
> 2. Read [source metadata](https://skilld.dev/api/v1/skills/comet-ml/opik/write-docs) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit.
> 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call:
>
> ```sh
> git init --quiet "$temporary_dir"
> git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit"
> git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD
> ```
>
> Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop.
> 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/write-docs`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md.
> Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical.
> 5. In the project root, run `skilld install ./skills/write-docs --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/write-docs --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure.
> 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks.

# Write Docs

The Opik docs site is built with [Fern](https://buildwithfern.com/) from MDX sources under `apps/opik-documentation/documentation/fern/`. There is one content surface: `fern/docs-v2/`. The old v1 surface (`fern/docs/`) was removed; every v1 URL now redirects to its Opik 2 equivalent through the `redirects:` list in `fern/docs.yml`.

## Where new pages live

- Create the file at `apps/opik-documentation/documentation/fern/docs-v2/<section>/<page-name>.mdx`.
- Register it in `fern/docs.yml` under the right `section:` block in `navigation:`.
- Routing is not implied by folder layout. Always check `navigation:` in `fern/docs.yml`.

## Frontmatter template

Every page uses YAML frontmatter. `title` and `headline` are required; the `og:*` fields are strongly recommended for SEO/social sharing and are present on every page. Do not repeat `title` as an inline `# H1` in the body — Fern renders it from frontmatter.

```yaml
---
title: Page Title
headline: Page Title | Opik Documentation
og:title: Page Title — Opik
og:description: One-line summary used for social sharing and previews
og:site_name: Opik Documentation
---
```

`subtitle: ...` is an optional field used on concept/overview pages to add a secondary line. Landing/overview pages may also set `layout: overview`.

## Style and voice

Pull examples from existing pages when unsure — `fern/docs-v2/tracing/advanced/log_traces.mdx`, `fern/docs-v2/tracing/concepts.mdx`, and `fern/docs-v2/quickstart.mdx` are good anchors.

- **Person:** "you" and imperative voice. Professional but approachable.
- **Opening:** one or two intro sentences before the first `##` heading. No inline H1.
- **Headings:** `##` for top-level sections, `###` for subsections. Never introduce an inline `#` — that collides with the frontmatter title.
- **Paragraphs:** keep them short (2–4 sentences). Mix prose with bullet lists for features, options, and prerequisites.
- **Page shape:**
  - *Concept pages* start with the *why*, then definitions.
  - *How-to pages* start with brief context, then the task steps.
  - *Overview/landing pages* lead with a short pitch and a `<CardGroup>` of links.
- **End with "## Next steps"** linking to 2–4 related pages when useful.

## Fern MDX components

All examples below are taken from real pages in the repo.

### `<Tabs>` / `<Tab>` — SDK, language, or environment choice

Use when the whole section varies (not just a code block). Attach `language="..."` so Fern groups tabs across the site by the reader's last choice.

```mdx
<Tabs>
  <Tab value="Python SDK" title="Python SDK" language="python">
    ```bash
    pip install opik
    ```
  </Tab>
  <Tab value="Typescript SDK" title="Typescript SDK" language="typescript">
    ```bash
    npm install opik
    ```
  </Tab>
  <Tab value="OpenTelemetry" title="OpenTelemetry">
    ...
  </Tab>
</Tabs>
```

### `<Steps>` / `<Step>` — walkthroughs

For quickstarts, installs, and any sequential procedure. `title` on each `<Step>` is optional.

```mdx
<Steps>
  <Step title="Install the Opik skill">
    ```bash
    npx skills add comet-ml/opik-skills
    ```
  </Step>
  <Step title="Run the integration">
    Once the skill is installed, you can add tracing using the following prompt:
    ```
    Instrument my agent with Opik using the /opik-instrument command.
    ```
  </Step>
</Steps>
```

### `<CodeBlocks>` — multi-language code, identical surrounding prose

Prefer this over `<Tabs>` when only the code varies.

```mdx
<CodeBlocks>
  ```python title="Python"
  import opik
  opik.configure()
  ```
  ```ts title="Typescript"
  import Opik from "opik";
  const client = new Opik();
  ```
</CodeBlocks>
```

### `<CardGroup>` / `<Card>` — landing and integration grids

```mdx
<CardGroup cols={3}>
  <Card title="LangChain" href="/integrations/langchain" icon={<img src="/img/tracing/langchain.svg" />} iconPosition="left"/>
  <Card title="LlamaIndex" href="/integrations/llama_index" icon={<img src="/img/tracing/llamaindex.svg" />} iconPosition="left"/>
  <Card title="Anthropic" href="/integrations/anthropic" icon={<img src="/img/tracing/anthropic.svg" />} iconPosition="left"/>
</CardGroup>
```

### `<AccordionGroup>` / `<Accordion>` — FAQs and expandable advanced topics

```mdx
<AccordionGroup>
  <Accordion title="Why use the optimizer?">
    The Agent Optimizer provides a unified interface...
  </Accordion>
</AccordionGroup>
```

### `<Frame>` — image wrapper (always wrap images)

```mdx
<Frame>
  <img src="/img/tracing/introduction.png" />
</Frame>
```

### Callouts: `<Tip>`, `<Note>`, `<Warning>`, `<Info>`, `<Callout>`

Pick by intent, not aesthetics:

- **`<Tip>`** — cross-references, shortcuts, "If you're just getting started, see..."
- **`<Note>`** — clarifications and recommendations that aren't risky
- **`<Warning>`** — breaking changes, footguns, prerequisites that will break things
- **`<Info>`** — informational, interchangeable with `<Note>` in practice
- **`<Callout>`** — catch-all when none of the above fits

```mdx
<Tip>
  If you are just getting started with Opik, we recommend first checking out the [Quickstart](/quickstart) guide.
</Tip>

<Warning>
  Note that the authorization header value does not include the `Bearer ` prefix.
</Warning>
```

## Code examples

- Use `<CodeBlocks>` for multi-language blocks; use `<Tabs>` when surrounding prose also varies.
- Install commands are inline bash blocks (`pip install opik`, `npm install opik`).
- There is no snippet-include system. All code is written inline in MDX.
- **Use placeholders for credentials:** `<API_KEY>`, `<TOKEN>`, `<your-api-key>`. Never commit real keys.

## Images

- Store under `apps/opik-documentation/documentation/fern/img/<section>/...`.
- Reference from MDX as `/img/<section>/<file>.png` (path is rooted at the docs base).
- **Never** put new assets in `static/img/` — that folder is legacy and only kept for external integrations.
- Always wrap with `<Frame>`. Captions are not a repo convention.

## Cross-links

Root-relative, slug-based paths only (`/section/page`).

- **Never** link internal docs pages with full `https://www.comet.com/docs/opik/...` URLs. Full URLs bypass the Fern preview build, and they 404 in the link checker when the target page ships in the same PR. Use the root-relative slug path instead.
- No file-relative paths (`../foo`) either.
- Build the path from `navigation:` in `fern/docs.yml`, including every nested `section:` slug. Example: the "Manage datasets" page sits inside an `advanced` section, so the path is `/evaluation/advanced/manage_datasets`, not `/evaluation/manage_datasets`.

```mdx
[Python SDK](/reference/python-sdk/overview)
[Log traces](/tracing/advanced/log_traces)
[Integrations overview](/integrations/overview)
```

In-page anchors use the heading slug: `[Concepts](#concepts)`.

## Routing: adding a page to `docs.yml`

Add a page entry under the correct `section:` in `navigation:` (keep the YAML at 2-space indent):

```yaml
- page: Page Title
  path: ./docs-v2/section/page-name.mdx
  slug: page-name
```

## File naming

- Kebab-case for new files: `getting-started.mdx`, `log-traces.mdx`.
- When editing an existing section that uses snake_case, match neighbors rather than renaming. Renames require redirect entries in `docs.yml`.

## Local verification

```bash
cd apps/opik-documentation/documentation
npm install          # first time only
npm run dev          # live-reload preview
```

Open the rendered page and confirm:
- Frontmatter renders (title shows, no stray H1 in body).
- Every MDX component resolves (no raw `<Tabs>` tags visible).
- Every link works (no 404s, no `Broken link` warnings in the terminal).
- Images load.

## Changelog routing

Pick the changelog target by scope — do not default everything to one surface.

- `apps/opik-documentation/documentation/fern/docs-v2/self-host/changelog.mdx` — self-hosted deployment changelog shown at `/docs/opik/self-host/changelog`. Breaking, critical, or security-impacting changes only. (The former repo-root `CHANGELOG.md` was removed; its content lives on this page now.)
- `apps/opik-documentation/documentation/fern/docs-v2/changelog/*.mdx` — general product release notes shown at `/docs/opik/changelog`. One dated `.mdx` per entry.
- `apps/opik-documentation/documentation/fern/docs-v2/development/optimization-runs/changelog.mdx` — Agent Optimizer version updates (e.g. `sdks/opik_optimizer` releases like `3.1.0`).
- Liquibase `changelog.xml` files are migration manifests, not user-facing release notes. Do not put prose there.
- When unsure, confirm the surface from `fern/docs.yml` before editing.

### Changelog entry template

```markdown
### [VERSION] - [DATE]

#### New Features
- **Feature Name**: Brief description

#### Improvements
- **Improvement**: What changed and why

#### Bug Fixes
- **Fix**: What was broken (#issue)

#### Breaking Changes
- **Change**: What breaks, migration steps
```

## Feature documentation checklist

When documenting a new feature, cover:

- **User impact** — What capability does this add? How do users access it?
- **Technical changes** — API endpoints and params, SDK methods, config or env vars, migrations.
- **Breaking changes** — What breaks and the migration path, if any.

Keep it user-facing: avoid implementation detail unless it affects how someone uses the feature.

## PR description template

Use the repository template at `.github/pull_request_template.md` — read the FULL file before drafting (the required sections continue past the first screen). CI (`.github/workflows/pr-lint.yml`) fails any PR whose description is missing one of these exact headings:

- `## Details`
- `## Change checklist`
- `## Issues`
- `## Testing`
- `## Documentation`

Also fill in the template's `## AI-WATERMARK` section (yes/no; if yes: Tools, Model(s), Scope, Human verification). Never invent a different structure such as `## Summary` / `## Test Plan`.

A section that does not apply gets `N/A` — never delete a heading.

### `## Details` — style

Write what changes for a user. A reviewer reads the diff for the code; this section tells them what is different when they use the product.

- **Short.** Most PRs need 3–10 bullets. If it runs longer, the section is doing the diff's job — cut it.
- **Bullets, not prose paragraphs.** One behavior per bullet. Nest one level for sub-cases.
- **Authoritative.** State what happens: "The run is scored once." Not "This should now mean that the run will be scored once."
- **No fluff.** No motivation paragraph, no "this PR …", no approach summary, no benefits list, no restating the diff.
- **Observable behavior first.** What the UI shows, what the API returns, what gets scored, stored or logged. Name a class, method or file only when the behavior makes no sense without it.

Pick the shape that fits the change — do not force one:

- **Before / After bullet lists** when a behavior changed and the contrast is the point.
- **A flat bullet list** for a new capability, where there is no "before".
- **One or two lines** when users cannot see the change (refactor, dependency bump) — say what is unchanged and what improved, then stop.

## Internationalized READMEs

`readme_CN.md`, `readme_ES.md`, `readme_FR.md`, `readme_DE.md` are AI machine-translated from the English `README.md`.

- Each non-English README has a blockquote notice at the top warning that it is AI-translated and welcoming improvements. Keep it.
- When the English README changes meaningfully, re-translate the affected files. Do not hand-edit translated READMEs for content changes — update the English source and re-translate.

## Forbidden and discouraged

- No real API keys, tokens, or workspace IDs in examples — always placeholders.
- Do not put new images outside `fern/img/`. `static/img/` is legacy-only and cannot be deleted because of external integrations.
- Do not infer URL paths from folder layout — always consult `navigation:` in `fern/docs.yml`.
- Do not add an inline `# H1` inside the body — the frontmatter `title` already provides it.

## Key files

- `apps/opik-documentation/documentation/fern/docs.yml` — site config: tabs, `navigation:` routing, and `redirects:`. Edit `navigation:` when adding pages.
- `apps/opik-documentation/documentation/fern/docs-v2/` — target directory for new pages.
- `apps/opik-documentation/documentation/fern/img/` — image storage.
- `apps/opik-documentation/AGENTS.md` — docs-module contribution rules.
- `.github/release-drafter.yml` — release notes template.
