# AI‑Powered Section Rewrite – How to Quickly Re‑write Parts of Your Help Articles

# AI‑Powered Section Rewrite – How to Quickly Re‑write Parts of Your Help Articles

You can now ask the AI to rewrite a single section of an article directly from the dashboard.
Give a short instruction (e.g., “Make this paragraph shorter” or “Add an example”) and see the proposed changes as a live diff before you apply them.

---

## What’s new?

| Feature             | What it does                                                                                                                                                    |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Section Rewrite** | Adds a “Rewrite” card under any article section. You type an instruction, the AI returns a revised markdown version, and you can preview the changes as a diff. |
| **Diff view**       | Shows added lines in green, removed lines struck‑through, and folds long unchanged runs. The view is used in the rewrite card and in the **Doc Health** page.   |
| **API endpoint**    | The dashboard now calls a new backend route (`POST /articles/rewrite-section`) that returns the rewritten markdown and any source references.                   |
| **UI updates**      | The editor toolbar includes a new **Sparkles** button, and the article workspace automatically passes the rewrite request to the API.                           |

These changes are available in the **main** deployment of the Usedocs dashboard. No extra configuration is required on your side.

---

## How to rewrite a section

1. **Open the article you want to edit**
 From the dashboard, go to **Help → Articles**, pick a draft or published article, and click **Edit**.
2. **Select the target section**
 Click anywhere inside the paragraph, list, or block you want to change. The editor will highlight the selected block.
3. **Open the Rewrite card**
   - Type `/` to open the block menu and choose **“Rewrite with AI”** (or click the **Sparkles** icon in the toolbar).
   - A card appears directly under the selected section.
4. **Enter an instruction**
 Write a short command describing the desired change.
 *Examples:*
   - “Make this shorter”
   - “Use simpler words”
   - “Turn this into numbered steps”
   - “Add a short example”
   - “Make the tone friendlier”

    The instruction field accepts up to **500 characters**.
5. **Run the rewrite**
 Click **Generate** (or press **Enter**). The dashboard sends a request to the new `rewriteArticleSection` API endpoint with:
   - Article title
   - Full markdown body
   - The markdown of the selected section
   - Your instruction
6. **Preview the diff**
 The card shows a **DiffView**:
   - **Green lines** – text added by the AI.
   - **Strikethrough lines** – text removed.
   - **Ellipsis (⋯)** – folded unchanged runs.

    Review the changes. If you need a different result, edit the instruction and click **Generate** again.
7. **Apply the rewrite**
   - Click **Replace** to substitute the original section with the AI‑generated markdown.
   - The editor updates in place, so you can still **Undo (⌘ Z)** if you change your mind.
   - When you’re satisfied, **Save** the article as usual.

---

## Where the diff view is also used

The new **DiffView** component is now part of the **Doc Health** page. When you view a proposed revision, the diff is displayed with the same colour‑coding and folding behaviour, making it easier to spot large changes.

---

## Caveats & best‑practice tips

| Issue                  | What to know / Do                                                                                                           |
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| **Instruction length** | The instruction is limited to 500 characters. Keep it concise for the best results.                                         |
| **No automatic save**  | The rewrite only updates the editor buffer. You must click **Save** (or **Publish**) to persist the change.                 |
| **AI may hallucinate** | The AI can add content that isn’t verified. Review the diff carefully and edit any inaccurate statements before publishing. |

---