# Update and review documentation

import { Aside, Steps, Tabs, TabItem } from '@astrojs/starlight/components';

Use update mode when documentation exists but needs changes. Use review mode to get feedback without modifying content.

## Update from tickets

When a feature ships or a bug is fixed, update documentation by referencing the ticket. The agent reads the ticket details and identifies which docs need changes.

**Works with:** Linear, Jira

<Tabs>
  <TabItem label="Basic update">
    ```
    Update the documentation based on Linear ticket ENG-1234.
    ```
  </TabItem>
  <TabItem label="With context">
    ```
    ENG-1234 added rate limiting to the API. Update the
    API reference with the new rate limit headers and
    error responses.
    ```
  </TabItem>
  <TabItem label="Multiple tickets">
    ```
    Update the authentication docs based on ENG-1234,
    ENG-1235, and ENG-1236.
    ```
  </TabItem>
</Tabs>

<Aside type="tip">
Adding context about what changed helps the agent make more accurate updates.
</Aside>

## Update from code changes

Point the agent to code changes and it updates relevant documentation.

```
The login flow changed in the last commit. Update the
authentication guide to reflect the new OAuth
implementation in src/auth/.
```

```
We deprecated the /api/v1/users endpoint. Update the
API reference to mark it as deprecated and point to
the v2 replacement.
```

## Update specific sections

Target specific parts of a document instead of regenerating everything.

```
Update only the "Configuration" section in
docs/getting-started.md with the new environment
variables from .env.example.
```

```
Add a "Troubleshooting" section to the deployment guide
covering the three most common issues from our support
tickets.
```

This is useful when you want precise edits without affecting the rest of the document.

## Review documentation

Get AI feedback on existing documentation without making changes. The agent analyzes your content and provides suggestions.

:::tip
For automated style enforcement on every pull request, pair Docs Agent with [Docs Reviewer](/reviewer/quickstart/). The agent generates and updates content — the reviewer catches style violations, inconsistent terminology, and formatting issues before they merge.
:::

### What the agent checks

| Aspect | What it looks for |
|--------|-------------------|
| **Clarity** | Are instructions easy to follow? Is the language clear? |
| **Completeness** | Are steps missing? Are edge cases covered? |
| **Accuracy** | Does the documentation match the current code? |
| **Consistency** | Does terminology match other docs? Is formatting consistent? |

### Example prompts

```
Review the getting started guide and suggest improvements
for clarity and completeness.
```

```
Review the API reference for the authentication endpoints.
Check if the examples still work with the current code.
```

```
Review docs/deployment.md from the perspective of a
developer who has never deployed this application before.
```

### Applying suggestions

The agent provides feedback in the chat panel. You can:

1. Apply suggestions you agree with by asking the agent to make the change
2. Edit directly in the editor panel
3. Iterate by asking for more specific feedback

## Verify before publishing

### View changes

Enable **View All Changes** in the toolbar to see a diff of all modifications. Review each change before creating a pull request.

Look for:
- Unintended deletions.
- Formatting issues.
- Content that needs adjustment.

### Link validation

The agent automatically validates links and email addresses in generated content. If it detects broken links, it regenerates the affected sections with corrections.

### Create a pull request

When satisfied with the changes:

<Steps>
1. Click **Raise PR** in the toolbar.

   The agent prefills a prompt in the chat panel — for example, `Open a pull request` or `Open a pull request for my-org/my-repo` when you have changes across multiple repositories.

2. Edit the prompt if you want to add instructions, then press **Enter** to send it.

3. The agent creates the pull request and responds in the chat with a link to the PR.
</Steps>

If your session spans multiple repositories, click the **Raise PR** dropdown to select a specific repository.

<Aside type="note">
Pull requests include both text and binary files. If the agent inserted images or screenshots during the session, those files commit alongside your documentation changes.
</Aside>

### Update an existing pull request

After a PR is open, you can push more changes to it:

<Steps>
1. Make further edits in the editor or ask the agent for more changes in the chat.

2. Click **Update PR** in the toolbar when new changes are ready.

   The agent prefills a prompt like `Update pull request #42 with my latest changes`.

3. Edit the prompt if needed, then press **Enter**.

4. The agent commits and pushes your changes to the existing PR branch.
</Steps>

<Aside type="tip">
When your PR is already up to date, the toolbar shows a **View PR** link that opens the pull request on GitHub in a new tab.
</Aside>

## Next steps

- [Create documentation](/agent/create) — Generate READMEs, API references, and guides from your codebase.
- [Scheduled agents](/agent/scheduled-agents) — Automate recurring doc tasks like drift audits and freshness checks.
- [Integrations](/agent/integrations) — Connect Slack, Notion, Linear, Jira, and other tools.
- [Set up automated review](/reviewer/quickstart) — Run EkLine Docs Reviewer in your CI/CD pipeline to catch issues before they merge.