mirror of
https://github.com/mintlify/docs.git
synced 2026-09-14 13:35:46 +08:00
mintlify-development[bot]
78 lines
3.7 KiB
Plaintext
78 lines
3.7 KiB
Plaintext
---
|
|
title: "Pre-publish polish checklist"
|
|
sidebarTitle: "Pre-publish checklist"
|
|
description: "Run this checklist before shipping a docs change to catch broken links, missing assets, and formatting issues while the change is still cheap to fix."
|
|
keywords: ["pre-publish checklist", "polish docs", "validate documentation", "broken links", "docs review"]
|
|
---
|
|
|
|
Small issues — a broken link, a missing alt text, a stray "TODO" — are cheap to fix before a change ships and expensive to fix after. Run this checklist on every non-trivial docs change before you merge.
|
|
|
|
## Content
|
|
|
|
Read the page top to bottom once, out loud if you can.
|
|
|
|
- **Frontmatter is complete.** `title`, `sidebarTitle` (if the title is long), and `description` are set. The `description` is a single sentence that stands on its own in search results.
|
|
- **Headings use sentence case.** "Getting started", not "Getting Started".
|
|
- **Voice is second-person and active.** "You configure the webhook," not "The webhook is configured by the user".
|
|
- **Prerequisites are stated up front** for any procedural content, before step 1.
|
|
- **No placeholders left behind.** Search the diff for `TODO`, `TK`, `FIXME`, `lorem ipsum`, and `xxx`.
|
|
|
|
## Links
|
|
|
|
Broken and hardcoded links are the most common polish miss.
|
|
|
|
- **Internal links are root-relative.** Use `/essentials/navigation`, never `https://docs.example.com/essentials/navigation`.
|
|
- **External links point at canonical URLs**, not redirects or tracking wrappers.
|
|
- **Anchors resolve.** If you link to `/guides/media#video`, confirm that heading still exists.
|
|
- **Run the broken-link check:**
|
|
|
|
```bash
|
|
mint broken-links
|
|
```
|
|
|
|
## Code blocks
|
|
|
|
- **Every code block has a language tag** (` ```bash `, ` ```ts `, ` ```json `). Untagged blocks lose syntax highlighting and copy affordances.
|
|
- **Commands are copy-pasteable.** No leading `$`, no smart quotes, no trailing prose on the same line.
|
|
- **Placeholder values are obvious** — `YOUR_API_KEY`, not `sk-abc123` that looks real.
|
|
|
|
## Images and media
|
|
|
|
- **Assets live in the repo**, not on a personal Dropbox or Notion link.
|
|
- **Alt text describes the content**, not the file (`"Analytics dashboard showing 30-day traffic"`, not `"screenshot.png"`).
|
|
- **Screenshots reflect the current UI.** Retake anything that shows an old logo, deprecated menu item, or stale copy.
|
|
- **File sizes are reasonable.** Compress screenshots over ~500 KB before committing.
|
|
|
|
## Navigation
|
|
|
|
- **The page is reachable.** Add it to `docs.json` under the right group — an orphaned page is effectively unpublished.
|
|
- **The sidebar title fits.** If `title` is longer than ~30 characters, set a shorter `sidebarTitle`.
|
|
- **Ordering is intentional.** New pages usually belong next to the most similar existing page, not at the bottom of the group.
|
|
|
|
## Validate
|
|
|
|
Run both commands from the repo root and fix any errors before merging. Warnings are safe to defer.
|
|
|
|
```bash
|
|
mint validate
|
|
mint broken-links
|
|
```
|
|
|
|
## Preview
|
|
|
|
- **Open the local preview** (`mint dev`) and click through the changed pages on desktop and mobile widths.
|
|
- **Test any interactive elements** — accordions, tabs, code groups, API playground requests.
|
|
- **Verify redirects** in `redirects.json` if you renamed or moved a page.
|
|
|
|
## Review
|
|
|
|
- **Diff is scoped.** No unrelated formatting churn, no accidental edits to other pages, no committed `.DS_Store` or editor config files.
|
|
- **Commit message uses a semantic prefix.** `feat:`, `fix:`, `docs:`, `chore:`, or `refactor:`.
|
|
- **PR description explains the _why_**, not just the _what_. Reviewers can read the diff for the what.
|
|
|
|
## Related
|
|
|
|
- [Style and tone](/guides/style-and-tone)
|
|
- [Maintenance](/guides/maintenance)
|
|
- [How to measure and improve documentation quality](/guides/improving-docs)
|