# Get better docs from your repository

Prepare your repository, write useful instructions, and review a draft so the first run is close to publishable.

Docup writes from what it can verify in your code, so the quality of the draft follows the quality of what is in the repository. A little preparation makes a large difference.

## Before the first run

### Make the repository explain itself

The planner starts from the file list and your README. These give the writer solid facts to work from:

- **A README** that says what the project is, who uses it and how to install it.
- **Configuration that is visible.** An `.env.example` or a config file with comments lets Docup document every option instead of guessing.
- **Named entry points.** Clear folder names such as `commands/`, `routes/` or `api/` help the planner choose pages.
- **Docstrings and comments** on public functions, routes and commands.
- **Typed or validated inputs.** Schemas and types are read as accurate reference material.

### Keep noise out

Add [ignore paths](/settings/guidance) for anything that is not part of the product: tests, fixtures, scripts, generated clients, vendored code, migrations, and design assets. A snapshot holds at most 1,500 files and 12 MB, and the planner works better on a focused set.

Docup automatically skips lockfiles, binaries, vendored folders, `.env` files, key files, and files that are empty or over 100 KB. You do not need to add these to your ignore list.

### Write instructions

Open **Settings → AI guidance** and brief the writer. Good instructions state the audience, the tone, and the scope.

```text
Audience: backend developers integrating our REST API. They know HTTP and JSON
but have never used our product.
Tone: direct and concrete. Short sentences. No marketing language.
Scope: document public endpoints, authentication and configuration. Skip
internal admin routes and anything under /debug.
Prefer a complete runnable example on every page that describes an endpoint.
```

Instructions are limited to 3,000 characters. They steer new pages and updates; they do not rewrite pages that already exist.

> **Tip:** Instructions affect pages written afterwards, not pages that already exist. Set them before your first run when you can. Re-planning the structure is marked as coming soon in [AI guidance](/settings/guidance), and regenerating all pages is marked as coming soon in [General settings](/settings/general); until then you can retry a page or edit it by hand.

## Review the draft

The AI states only what it verified, but you are the authority on your product. Spend your time where mistakes cost the most.

1. **Open the Overview checklist.** It lists failed pages, short pages and missing branding.
2. **Read the first two pages.** The overview and getting-started pages set the first impression and are the most visited.
3. **Run every command and code sample.** Copy them into a terminal.
4. **Check names, defaults and limits.** These are the details a reader acts on.
5. **Fill thin pages.** The Overview flags pages under 150 words.
6. **Add what only you know.** Why a design decision was made, known limitations, migration advice.
7. **Preview** the whole site and click every link.

## Make edits that last

When you edit a page, Docup treats it as yours and proposes suggestions rather than rewriting it. That is what you want for curated pages. For pages you want to follow the code automatically, leave them unedited.

- Prefer fixing facts in your **repository** (a comment, a README line) over patching the page, when the fact is wrong because the code is unclear. The next update then agrees with you.
- Use [callouts](/docs-site/markdown-reference) sparingly. One warning per page reads as a warning.
- Add your own pages for what the code cannot say: tutorials, comparisons, recipes. They are never touched by pushes.

## What to expect

Docup plans up to 15 pages for the first run, so a large product gets its main concepts documented first. Add pages by hand for the rest, or let updates add up to three new draft pages at a time as your code grows. See [Keeping docs up to date](/guides/updates).