# Tutorial: document a code change end to end

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

This tutorial walks you through the workflow at the heart of Docs Agent: keeping documentation in sync when your code changes. You start from an empty session and finish with a merged-ready pull request that updates your docs to match a change your team shipped.

By the end, you can:

- Connect a repository so the agent can read your code and existing docs.
- Ask the agent to update documentation for a specific code change.
- Review the draft, catch problems, and refine it with a follow-up prompt.
- Open a pull request and push a follow-up commit after review feedback.

The whole path takes about 20 minutes. Unlike [Getting started](/agent/getting-started/), which generates a single README, this tutorial follows a realistic change through review and revision — the loop you repeat every time your product evolves.

## Before you begin

You need:

- An EkLine account with Docs Agent enabled. Don't have access? Email **support@ekline.io** with your organization name.
- A repository that contains both code and Markdown documentation. Any repository with a `docs/` folder or a README works.
- Permission to open pull requests on that repository.

You don't need to write any code during this tutorial. You describe a change that already happened, and the agent updates the docs to match.

## Step 1: Connect your repository

The agent can only document code it can read, so connect a repository first.

<Steps>
1. Log in to your [EkLine dashboard](https://ekline.io/dashboard).
2. Click **Docs Agent** in the left navigation.
3. If you haven't connected a repository yet, follow [Connect GitHub to EkLine](/agent/github-app-setup/) to install the GitHub App and choose which repositories the agent can access.
</Steps>

**Verify:** The editor opens with a chat panel on the right and an editor panel on the left.

<img
    className={'rounded-2xl'}
    width={1288}
    height={711}
    src={`/assets/images/docs-agent-editor.png`}
    alt={`The Docs Agent editor with the sessions sidebar and chat panel ready for a prompt`}
/>

If you use GitLab instead, follow [Connect GitLab to EkLine](/agent/gitlab-setup/). The rest of this tutorial is the same.

## Step 2: Describe the change to document

Pick a change your team shipped recently — a new configuration option, a renamed endpoint, or a deprecated flag. For this tutorial, imagine your API added a `timeout` parameter to its authentication call.

In the chat panel, give the agent both the change and where it lives in the code:

```
We added a `timeout` parameter to the authentication call in
src/api/auth.ts. Update the API reference in docs/ to document
the new parameter, its type, its default, and an example.
```

<Aside type="tip" title="Point the agent at the source">
The more precisely you name the file and the change, the more accurate the draft. Reference the exact path (`src/api/auth.ts`) rather than describing it in general terms.
</Aside>

**Verify:** The agent responds in the chat and begins reading your repository. When it finishes, a draft of the updated documentation appears in the editor panel on the left.

## Step 3: Review the draft

Never ship the first draft unread. The agent is accurate, but you know your product — check that the change is described correctly before going further.

<Steps>
1. Read the draft in the editor panel.
2. Enable **View All Changes** in the toolbar to see a diff of every modification the agent made.
3. Look for three things:
   - **Accuracy** — Does the parameter type and default match your code?
   - **Placement** — Did the agent add the parameter to the right section?
   - **Unintended edits** — Did it change anything you didn't ask it to?
</Steps>

**Verify:** The diff shows your documentation with the new `timeout` parameter added, and no unrelated content removed.

## Step 4: Refine with a follow-up

Reviewing almost always surfaces something to improve. Instead of editing by hand, ask the agent — it keeps the change consistent with the surrounding docs.

Suppose the draft documents the parameter but omits what happens when the timeout is exceeded. Send a follow-up prompt:

```
Add a note explaining what error the API returns when the
timeout is exceeded, and cross-link it to the error reference.
```

The agent updates the same draft rather than starting over. You can refine as many times as you need — each prompt builds on the current state of the document.

<Aside type="note" title="Ask the agent to review its own work">
You can also ask for a critique before you ship: `"Review this page for completeness and accuracy against the current code."` The agent returns a checkpoint covering clarity, completeness, accuracy, and consistency.
</Aside>

<img
    className={'rounded-2xl'}
    width={1288}
    height={711}
    src={`/assets/images/docs-agent-review-checkpoint.png`}
    alt={`Docs Agent review checkpoint listing completeness, technical accuracy, and style compliance feedback in the chat panel`}
/>

**Verify:** The draft now includes the timeout error behavior and a link to the error reference.

## Step 5: Open a pull request

When the draft matches the change and reads well, ship it through your normal review process.

<Steps>
1. Click **Raise PR** in the toolbar.
2. The agent prefills a prompt such as `Open a pull request`. Edit it to add a title or description if you want, then press **Enter**.
3. The agent creates the pull request and responds in the chat with a link to it on GitHub.
</Steps>

**Verify:** The chat shows a link to a new pull request. Open it — the PR contains your documentation changes and nothing else.

## Step 6: Push a follow-up after review

Documentation goes through review like any other change. When a reviewer asks for an edit, you don't need to start a new session — push the fix to the same PR.

<Steps>
1. Back in the editor, ask the agent for the requested change. For example: `"The reviewer wants the example to use an environment variable instead of a hardcoded value. Update it."`
2. Click **Update PR** in the toolbar.
3. The agent prefills a prompt like `Update pull request #42 with my latest changes`. Press **Enter**.
</Steps>

**Verify:** The agent commits to the existing PR branch and confirms in the chat. Refresh the pull request on GitHub — the new commit appears in its history.

## Summary

You took a code change from an unread repository to a review-ready pull request. Along the way you:

- Connected a repository so the agent could read your code and docs.
- Documented a specific change by pointing the agent at the source file.
- Reviewed the draft for accuracy, placement, and unintended edits.
- Refined the content with follow-up prompts instead of editing by hand.
- Opened a pull request and pushed a follow-up commit after review.

This is the loop you repeat whenever your product changes. The more context you give the agent — file paths, tickets, linked sources — the closer each first draft lands.

## Next steps

- [Update and review documentation](/agent/update-review/) — More ways to update from tickets, commits, and specific sections.
- [Integrations](/agent/integrations/) — Pull context from Slack, Notion, Linear, Jira, and Confluence into your prompts.
- [Prevent documentation drift](/agent/prevent-documentation-drift/) — Catch out-of-date docs automatically with a scheduled review.
- [Set up automated style checks](/reviewer/quickstart/) — Enforce style guides on every pull request with Docs Reviewer.