From 3ff5fd0ce4bfac71e6ffe5e8fa01c2f1d5ff0235 Mon Sep 17 00:00:00 2001 From: "fern-api[bot]" <115122769+fern-api[bot]@users.noreply.github.com> Date: Thu, 13 Aug 2026 17:13:13 +0000 Subject: [PATCH 1/7] =?UTF-8?q?Completely=20rewrite=20the=20Fern=20Slack?= =?UTF-8?q?=20bot=20page=20and=20restructure=20its=20navigati=E2=80=A6?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- fern/products/docs/docs.yml | 8 +- fern/products/docs/pages/ai/fern-slack.mdx | 152 ++++++++++++++++ fern/products/docs/pages/ai/overview.mdx | 8 +- .../docs/pages/ask-fern/slack-app.mdx | 166 ------------------ 4 files changed, 159 insertions(+), 175 deletions(-) create mode 100644 fern/products/docs/pages/ai/fern-slack.mdx delete mode 100644 fern/products/docs/pages/ask-fern/slack-app.mdx diff --git a/fern/products/docs/docs.yml b/fern/products/docs/docs.yml index c676cbfa61..7b409e449a 100644 --- a/fern/products/docs/docs.yml +++ b/fern/products/docs/docs.yml @@ -182,8 +182,6 @@ navigation: contents: - page: Overview path: ./pages/ai/overview.mdx - - page: Fern Writer - path: ./pages/ai/writer.mdx - page: AI-generated examples path: ./pages/ai/ai-examples.mdx slug: ai-examples @@ -207,6 +205,9 @@ navigation: - page: MCP server path: ./pages/ai/mcp-server.mdx slug: mcp-server + - page: Fern in Slack + path: ./pages/ai/fern-slack.mdx + slug: fern-slack - page: API catalog discovery path: ./pages/ai/api-catalog.mdx slug: api-catalog @@ -229,9 +230,6 @@ navigation: - section: Setup skip-slug: true contents: - - page: Slack app - path: ./pages/ask-fern/slack-app.mdx - slug: slack-app - page: Custom guidance path: ./pages/ask-fern/guidance.mdx slug: guidance diff --git a/fern/products/docs/pages/ai/fern-slack.mdx b/fern/products/docs/pages/ai/fern-slack.mdx new file mode 100644 index 0000000000..99e373982e --- /dev/null +++ b/fern/products/docs/pages/ai/fern-slack.mdx @@ -0,0 +1,152 @@ +--- +title: Fern in Slack +description: >- + Tag @Fern in Slack to get instant answers from your documentation or update your docs via pull request — all without leaving Slack. +--- + +`@Fern` is a unified Slack bot that brings your documentation into your workflow. Tag it in any channel to get instant, cited answers to questions about your product, or ask it to update your docs and it will open a GitHub pull request with the changes. + +## What @Fern can do + + + + Ask @Fern anything about your product and it will search your documentation and reply with a cited answer in the thread. + + + Describe a docs change and @Fern will open a GitHub pull request with the edits. Review and iterate in the thread, then merge when ready. + + + +## Setup + +Installing @Fern in a Slack workspace requires Slack admin access. + +### Answer questions + + + +Use the [API Explorer](/learn/docs/ai-features/ask-fern/api-reference/slack-ask-fern/get-slack-install-link) to get a unique Slack installation link for your organization. Provide: +- Your Fern API key +- Your domain without protocol or path (e.g., `website.com`, not `https://website.com/docs`) + +Or use this cURL request: +```bash +curl -G https://fai.buildwithfern.com/slack/get-install \ + -H "Authorization: Bearer " \ + --data-urlencode domain= +``` + +Follow the URL returned in the `install_url` response field. + + +You'll be redirected to Slack to authorize the app. Select your workspace and click **Allow**. + + +Add @Fern to the channels where you want it to be available. Members will see `@Fern was added to the channel` and can start asking questions immediately. + + + +### Update docs + +Docs updates require a connected GitHub repository. GitLab and other Git providers are not currently supported. + + + +If you connected a repo through the Fern Dashboard, the GitHub App is already installed — skip this step. Otherwise, install it on your docs repo (requires GitHub org admin access). The app lets @Fern read your repository, open pull requests, and push commits attributed to `fern-support`. + + +Provide your Fern API key and the GitHub repository in `owner/repo` format (e.g., `acme/docs`): + +```bash +curl -G https://fai.buildwithfern.com/scribe/slack/get-install \ + -H "Authorization: Bearer " \ + --data-urlencode github_repo= +``` + +Follow the URL returned in the response. + + +You'll be redirected to Slack to authorize the app. Select your workspace and click **Allow**. + + +Add @Fern to the channels where your team discusses documentation. + + + +## Configuration + +### Bot settings per channel + +Use the `/fern` slash command in any channel to control how @Fern responds: + +| Command | Description | Example | +|---|---|---| +| `respond_to` | Set whether @Fern responds to `all` messages, `mentions_only` (when directly tagged), or `auto` (default — context-dependent). | `/fern respond_to all` | +| `roles` | Filter responses by RBAC roles (comma-separated), if role-based access control is configured. | `/fern roles developer,admin` | +| `show` | Display the current channel settings. | `/fern show` | +| `help` | Show available slash commands. | `/fern help` | + +### Customize the bot name + +You can rename @Fern to match your brand (e.g., `@Acme Support`): + +1. In Slack, go to **Apps** in the sidebar and click **Fern** +2. Click the **About** tab, then **Configuration** +3. Scroll to the **Bot User** section and click **Edit** +4. Enter your preferred name and save + +### Customize docs update behavior + +@Fern can be customized for docs updates via an `AGENTS.md` file in your docs repository. Use this file to define your writing style, preferred Fern components, and any conventions you want @Fern to follow when opening pull requests. + +## Answering questions + +When a member asks @Fern a question, it searches your documentation database and replies in the thread with a cited answer. + +### How it works + +1. A member asks @Fern a question in a channel +2. A Slack webhook fires to Fern's servers +3. The query is converted to a vector +4. If RBAC is enabled, user roles are checked +5. Relevant documentation chunks are retrieved +6. @Fern generates a response using the query and retrieved context +7. The answer is returned in the Slack thread +8. The question and answer are stored for [analytics](/learn/docs/ai-features/ask-fern/overview#analytics) + +### Improve answers over time + +You can teach @Fern from real interactions to improve future responses: + +1. A member asks a question and @Fern responds +2. If the answer needs improvement, reply in the thread with corrections or additional context +3. Ask @Fern to index the improved response (e.g., "Index this response") +4. @Fern drafts an improved Q&A pair — iterate until it looks right +5. Confirm, and @Fern saves the pair to the knowledge base + +Once indexed, @Fern uses the curated Q&A pair to inform future responses to similar questions. + +## Updating docs + +Tag @Fern in any channel and describe the change you need. @Fern will react to confirm receipt, then open a GitHub pull request and reply with a link. Request changes by replying in the thread. When the PR looks good, merge it. + +@Fern supports image and file attachments for additional context. When tagged in an existing thread, it reads the full conversation before responding. + +### Pull request attribution + +Each pull request includes a **Requested by** field attributing the change to the person who initiated it. Commits are signed and attributed to `fern-support`, making automated changes clearly distinguishable from manual contributions. + +### Example requests + +- `@Fern document the new rate limiting feature added in PR #123` +- `@Fern add a section about webhook retry behavior to the webhooks guide` +- `@Fern merge the authentication and authorization pages and add a redirect from the old URL` +- `@Fern fix the broken code example in the quickstart and update the package version to v2.1.0` + +## Privacy and data handling + +@Fern does not store your Slack messages directly. When you tag @Fern or reference a thread, the content is held in a session to complete the task and is **not retained** afterwards. + +Neither Fern nor its underlying AI providers use your data to train models. Your channel messages, code, and documentation content are never used for training purposes. + +Questions and answers from Q&A interactions are stored for [analytics purposes](/learn/docs/ai-features/ask-fern/overview#analytics). diff --git a/fern/products/docs/pages/ai/overview.mdx b/fern/products/docs/pages/ai/overview.mdx index 94232015e3..6b0f86ddfe 100644 --- a/fern/products/docs/pages/ai/overview.mdx +++ b/fern/products/docs/pages/ai/overview.mdx @@ -20,21 +20,21 @@ Your documentation site comes with automatic optimizations for AI tools, plus fe ## Find answers -Help users get instant, cited answers from your documentation wherever they're working. Ask Fern is available as an embedded chat widget, an [API](/learn/docs/ai-features/ask-fern/api-reference/overview) for custom integrations, and a [Slack app](/learn/docs/ai-features/ask-fern/slack-app) for your community. For developers in AI clients like Claude Code, Cursor, and Windsurf, Fern also hosts an MCP server so they can query your docs directly from their development environment. +Help users get instant, cited answers from your documentation wherever they're working. Ask Fern is available as an embedded chat widget, an [API](/learn/docs/ai-features/ask-fern/api-reference/overview) for custom integrations, and [@Fern in Slack](/learn/docs/ai-features/fern-slack) for your community. For developers in AI clients like Claude Code, Cursor, and Windsurf, Fern also hosts an MCP server so they can query your docs directly from their development environment. - + ## Create and update content -AI helps keep your documentation current. Fern Writer is a Slack-based technical writing agent that creates pull requests with targeted edits when you tag `@Fern Writer` to request updates. For API Reference docs, Fern automatically generates realistic examples from your OpenAPI spec that stay synchronized with spec changes, replacing placeholder values like `"string"` with believable data. +AI helps keep your documentation current. [@Fern in Slack](/learn/docs/ai-features/fern-slack) is a Slack-based technical writing agent that creates pull requests with targeted edits when you describe a change. For API Reference docs, Fern automatically generates realistic examples from your OpenAPI spec that stay synchronized with spec changes, replacing placeholder values like `"string"` with believable data. - + diff --git a/fern/products/docs/pages/ask-fern/slack-app.mdx b/fern/products/docs/pages/ask-fern/slack-app.mdx deleted file mode 100644 index 506d77236b..0000000000 --- a/fern/products/docs/pages/ask-fern/slack-app.mdx +++ /dev/null @@ -1,166 +0,0 @@ ---- -title: Ask Fern Slack app -description: Enable your customers to get instant answers to product questions directly in Slack using Ask Fern's AI-powered documentation bot. ---- - - -The Ask Fern Slack app allows customers to ask questions about your products directly in Slack channels and receive AI-generated answers from your documentation database. - -Fern stores all questions and answers from Slack interactions for [analytics purposes](/learn/docs/ai-features/ask-fern/overview#analytics). - -## Setup - -Install the Ask Fern app in your workspace and add the bot to customer channels. - - - To install Ask Fern in your organization's Slack workspace, you must be a Slack admin. - - - - - -Use the [API Explorer](/learn/docs/ai-features/ask-fern/api-reference/slack-ask-fern/get-slack-install-link) to get a unique Slack installation link for your organization. Provide: -- Your Fern API key -- Your domain without protocol or path (e.g., `website.com`, not `https://website.com/docs`) - -You can alternatively use this cURL request: -```bash -curl -G https://fai.buildwithfern.com/slack/get-install \ - -H "Authorization: Bearer " \ - --data-urlencode domain= -``` - -Follow the URL returned in the `install_url` response field. - - - -You'll be redirected to Slack to authorize the Ask Fern app. Select the workspace where you want to add Ask Fern and click **Allow**. - - - Allow Ask Fern for Slack workspace - - - - - -Once you've installed it in your workspace, add the bot to customer Slack channels to give it access. Customers will see that `@Ask Fern was added to the channel` and can start asking questions immediately. - - - - -## Configuration - -Customize the bot's behavior to match your workflow needs. - -### Bot settings per channel - -Use the `/fern` slash command in any channel to adjust the settings: - -| Command | Description | Example | -|---------|-------------|---------| -| **respond_to** | Controls whether the Ask Fern bot responds to all messages (`all`), reponds only when directly mentioned with `@Ask Fern` (`mentions_only`), or determines when to respond to messages depending on context (`auto`). Set to `auto` by default. | `/fern respond_to all` | -| **roles** | Specifies which RBAC roles (comma-separated) should be used to filter Ask Fern responses (if you have [role-based access control](/learn/docs/authentication/features/rbac) configured) | `/fern roles developer,admin` | -| **show** | Show the current settings | `/fern show` | -| **help** | Get help with Ask Fern slash commands | `/fern help` | - - - Respond all setting in Slack - - -### Customize the bot name - -You can rename the bot to match your brand (example: "YourCompanyName Support"): - -1. In Slack, go to **Apps** in the sidebar and click **Ask Fern** -2. Click the **About** tab, then **Configuration** -3. Scroll to **Bot User** section and click **Edit** -4. Enter your preferred bot name and save changes - - - Update name of Slackbot - - -Now customers will see `@YourCompanyName Support was added to the channel` instead of the default `@Ask Fern` name. - -### Collaborative FAQ generation - -You can improve the Slack bot's knowledge base by teaching it from real customer interactions. When the bot provides answers in Slack, you can refine those responses and save them for future reference. - -How it works: - -1. **A user asks a question** - The bot responds in the channel -2. **Review the response** - If the answer needs improvement, reply in the thread to the bot's message -3. **Provide corrections** - Add missing context, correct inaccuracies, or clarify the response -4. **Request indexing** - Ask the bot to index the improved response (e.g., "Index this response" or "Please save this") -5. **Iterate if needed** - The bot will generate an improved answer. Continue refining until you're satisfied -6. **Confirm indexing** - When the response looks good, tell the bot to save it. The bot will confirm the Q&A pair has been indexed - -Once indexed, Ask Fern will use this curated question-answer pair to inform future responses to similar questions, giving more accurate answers over time. - - - - -**User –** *@PlantSupport* what's the best way to care for succulents -indoors? - -**Plant Support bot –** Succulents need bright, indirect light and should be watered every 2-3 weeks. Make sure the soil dries out completely between waterings. - -**Support Lead –** *@PlantSupport* This is good but you should mention drainage holes and the -risk of root rot. Also, watering frequency depends on the season - less in -winter. Let's index this thread. - -**Plant Support bot:** I'd be happy to help you index this thread! Let me work -with you to create a clear Q&A pair for your knowledge base. Based on the -conversation, the main question is about caring for indoor succulents. Let me -draft an improved Q&A pair: - -Question: "What's the best way to care for succulents indoors?" - -Ideal Response: - -Succulents thrive indoors with the following care:* - -- Light: Provide bright, indirect sunlight (6+ hours daily near a south or east-facing window) -- Watering: Water thoroughly every 2-3 weeks during spring and summer, -reducing to once a month in winter. Always wait until the soil is -completely dry between waterings -- Drainage: Use pots with drainage holes and well-draining soil -(cactus/succulent mix) to prevent root rot -- Warning: Overwatering is the most common cause of succulent death. Root rot -develops quickly in waterlogged soil - -Does this capture the question and response accurately? Would you like me to adjust anything before saving it to your knowledge base? - -**Support Lead:** *@PlantSupport* Perfect! Please save this. - -**Plant Support bot –** Successfully indexed! This Q&A pair has been added to your knowledge base and will be used to inform future responses about indoor succulent care. - - - - -## Architecture - -When a user asks Ask Fern a question in Slack, a webhook triggers Fern's servers to search your documentation database and retrieve relevant context. Using that context, Ask Fern generates a response. - - -```mermaid -sequenceDiagram - autonumber - participant U as User (Slack) - participant S as Slack Webhook - participant F as Fern Servers - participant V as Documentation Database - participant A as Ask Fern - - U->>S: Ask question to @Ask Fern - S->>F: Webhook fires to Fern servers - F->>F: Convert query to vector - F->>F: Check user roles (if RBAC enabled) - F->>V: Search for relevant chunks - V->>F: Return matching documents user can access - F->>A: Send query + context - A->>A: Generate response - A->>U: Return answer in Slack thread - F->>F: Store question and answer for analytics -``` - From 83ed1b3004be351b95213d8a9205c51a0e273282 Mon Sep 17 00:00:00 2001 From: "fern-api[bot]" <115122769+fern-api[bot]@users.noreply.github.com> Date: Thu, 13 Aug 2026 17:14:46 +0000 Subject: [PATCH 2/7] =?UTF-8?q?Add=20a=20new=20documentation=20page=20abou?= =?UTF-8?q?t=20"Fern=20Agent"=20=E2=80=94=20the=20agentic=20AI=20chat=20b?= =?UTF-8?q?=E2=80=A6?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- fern/products/docs/docs.yml | 3 + fern/products/docs/pages/ai/fern-agent.mdx | 80 ++++++++++++++++++++++ 2 files changed, 83 insertions(+) create mode 100644 fern/products/docs/pages/ai/fern-agent.mdx diff --git a/fern/products/docs/docs.yml b/fern/products/docs/docs.yml index c676cbfa61..13274c1e95 100644 --- a/fern/products/docs/docs.yml +++ b/fern/products/docs/docs.yml @@ -182,6 +182,9 @@ navigation: contents: - page: Overview path: ./pages/ai/overview.mdx + - page: Fern Agent + path: ./pages/ai/fern-agent.mdx + slug: fern-agent - page: Fern Writer path: ./pages/ai/writer.mdx - page: AI-generated examples diff --git a/fern/products/docs/pages/ai/fern-agent.mdx b/fern/products/docs/pages/ai/fern-agent.mdx new file mode 100644 index 0000000000..4e3eedaaa1 --- /dev/null +++ b/fern/products/docs/pages/ai/fern-agent.mdx @@ -0,0 +1,80 @@ +--- +title: Fern Agent +description: An agentic AI assistant built into the Fern Dashboard that lets you edit docs, explore analytics, and manage your organization — all in plain language. +--- + +Fern Agent is an AI assistant built directly into the [Fern Dashboard](https://dashboard.buildwithfern.com/). Instead of navigating menus and settings manually, you can describe what you want in plain language and Fern Agent will carry it out or point you in the right direction. + +## What you can do + +### Edit your docs + +Ask Fern Agent to make changes to any of your docs sites. It reads your source repository, makes the requested edits, and delivers them as a branch, a pull request, or a live draft in the visual editor — whichever you prefer. + + +Add a new page about authentication to my getting-started guide. + + +
+ + +Rewrite the introduction on the overview page to be more concise. + + +
+ + +Move the changelog section to the top of the sidebar. + + +### Explore analytics + +Ask questions about your docs traffic, reader behavior, and broken links without writing a single query. + + +Which pages got the most traffic last month? + + +
+ + +Are there any 404s on my site? + + +
+ + +Where is my traffic coming from? + + +### Review Ask AI activity + +Get a summary of what your readers are asking [Ask Fern](/learn/docs/ai-features/ask-fern/overview), which questions went unresolved, and what topics might need better documentation coverage. + + +What have readers been asking about this week? + + +
+ + +Show me unresolved Ask AI conversations. + + +### Manage your organization + +Ask about members, billing, API keys, and site settings. For actions that require dashboard access, Fern Agent links you directly to the right page. + + +Who are the admins in my organization? + + +
+ + +Where do I manage API keys? + + +## Getting started + +Fern Agent is available to all Fern users from the [Dashboard](https://dashboard.buildwithfern.com/). Open the dashboard and use the chat panel to start a conversation. No setup is required. From 941bc07629ebc6191dcbb7496ce17b2ad48451c4 Mon Sep 17 00:00:00 2001 From: "fern-api[bot]" <115122769+fern-api[bot]@users.noreply.github.com> Date: Thu, 13 Aug 2026 17:16:51 +0000 Subject: [PATCH 3/7] =?UTF-8?q?Add=20redirects=20to=20`docs.yml`=20for=20t?= =?UTF-8?q?he=20two=20pages=20that=20were=20moved=20or=20remove=E2=80=A6?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- fern/docs.yml | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/fern/docs.yml b/fern/docs.yml index b5582387ef..483d8e3e46 100644 --- a/fern/docs.yml +++ b/fern/docs.yml @@ -830,6 +830,11 @@ redirects: - source: /learn/ask-fern/:slug* destination: /learn/docs/ai-features/ask-fern/:slug* + - source: /learn/docs/ai-features/ask-fern/slack-app + destination: /learn/docs/ai-features/fern-slack + - source: /learn/docs/ai-features/fern-writer + destination: /learn/docs/ai-features/fern-slack + # Ask Fern new-location cleanup (/learn/docs/ai-features/ask-fern/*) - source: /learn/docs/ai-features/ask-fern/how-it-works destination: /learn/docs/ai-features/ask-fern/overview From 593e1219fd806fce4d7f99c65306a3afc660c68f Mon Sep 17 00:00:00 2001 From: "devin.logan" Date: Thu, 13 Aug 2026 17:25:53 +0000 Subject: [PATCH 4/7] fix(docs): correct Fern Agent page against the implementation Beta/allowlisted availability, dashboard editor-first delivery, actual analytics and org capabilities, plus a Fern Agent card on the AI features overview. Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> --- .vale/styles/Microsoft/BiasFree.yml | 14 ++++++ .vale/styles/Microsoft/ExclamationPoints.yml | 7 +++ .vale/styles/Microsoft/Jargon.yml | 11 +++++ .vale/styles/Microsoft/Militaristic.yml | 24 +++++++++ .vale/styles/Microsoft/QuestionMarks.yml | 7 +++ .vale/styles/Microsoft/UIVerbs.yml | 9 ++++ .vale/styles/Microsoft/Uppercase.yml | 11 +++++ fern/products/docs/pages/ai/fern-agent.mdx | 52 +++++++++++++------- fern/products/docs/pages/ai/overview.mdx | 5 +- 9 files changed, 121 insertions(+), 19 deletions(-) create mode 100644 .vale/styles/Microsoft/BiasFree.yml create mode 100644 .vale/styles/Microsoft/ExclamationPoints.yml create mode 100644 .vale/styles/Microsoft/Jargon.yml create mode 100644 .vale/styles/Microsoft/Militaristic.yml create mode 100644 .vale/styles/Microsoft/QuestionMarks.yml create mode 100644 .vale/styles/Microsoft/UIVerbs.yml create mode 100644 .vale/styles/Microsoft/Uppercase.yml diff --git a/.vale/styles/Microsoft/BiasFree.yml b/.vale/styles/Microsoft/BiasFree.yml new file mode 100644 index 0000000000..261e39b3d5 --- /dev/null +++ b/.vale/styles/Microsoft/BiasFree.yml @@ -0,0 +1,14 @@ +extends: substitution +message: "Consider '%s' instead of '%s'." +link: https://learn.microsoft.com/en-us/style-guide/bias-free-communication +level: warning +ignorecase: true +action: + name: replace +# Culturally sensitive terms; see GenderBias.yml for gendered terms. +swap: + '(?:demilitarized zone|DMZ)': perimeter network + 'master/slave': master/subordinate + 'sanity check': quick check + 'spirit animal': role model + hangs: stops responding diff --git a/.vale/styles/Microsoft/ExclamationPoints.yml b/.vale/styles/Microsoft/ExclamationPoints.yml new file mode 100644 index 0000000000..774fedf825 --- /dev/null +++ b/.vale/styles/Microsoft/ExclamationPoints.yml @@ -0,0 +1,7 @@ +extends: existence +message: "Use exclamation points sparingly." +link: https://learn.microsoft.com/en-us/style-guide/punctuation/exclamation-points +level: suggestion +nonword: true +tokens: + - '\w!(?:\s|$)' diff --git a/.vale/styles/Microsoft/Jargon.yml b/.vale/styles/Microsoft/Jargon.yml new file mode 100644 index 0000000000..999d43667a --- /dev/null +++ b/.vale/styles/Microsoft/Jargon.yml @@ -0,0 +1,11 @@ +extends: substitution +message: "Consider using '%s' instead of the jargon '%s'." +link: https://learn.microsoft.com/en-us/style-guide/word-choice/avoid-jargon +level: suggestion +ignorecase: true +action: + name: replace +swap: + bucketize: group + glyph: symbol + leverage: take advantage of diff --git a/.vale/styles/Microsoft/Militaristic.yml b/.vale/styles/Microsoft/Militaristic.yml new file mode 100644 index 0000000000..45c0f027db --- /dev/null +++ b/.vale/styles/Microsoft/Militaristic.yml @@ -0,0 +1,24 @@ +extends: substitution +message: "Consider '%s' instead of '%s'." +link: https://learn.microsoft.com/en-us/style-guide/militaristic-language +level: suggestion +ignorecase: true +action: + name: replace +# The guide scopes its table to cybersecurity writing, so the generic verbs it +# also lists (combat, fight, guard, ward) are omitted here: without that context +# they'd fire on ordinary prose. +swap: + '(?:cyber ?)?kill chain': cyberattack chain + 'defense-in-depth approach': multilayered approach + 'external attack surface': external exposure + 'first line of defense': protection + 'frontline analysts': security analysts + 'locked down': secured + adversaries: threat actors + adversary: threat actor + attackers: cyberattackers + attacker: cyberattacker + blast radius: impact + fortifications: protection + frontlines: defense diff --git a/.vale/styles/Microsoft/QuestionMarks.yml b/.vale/styles/Microsoft/QuestionMarks.yml new file mode 100644 index 0000000000..2034033c05 --- /dev/null +++ b/.vale/styles/Microsoft/QuestionMarks.yml @@ -0,0 +1,7 @@ +extends: existence +message: "Use questions sparingly." +link: https://learn.microsoft.com/en-us/style-guide/punctuation/question-marks +level: suggestion +nonword: true +tokens: + - '\w\?(?:\s|$)' diff --git a/.vale/styles/Microsoft/UIVerbs.yml b/.vale/styles/Microsoft/UIVerbs.yml new file mode 100644 index 0000000000..ed6ef85a1c --- /dev/null +++ b/.vale/styles/Microsoft/UIVerbs.yml @@ -0,0 +1,9 @@ +extends: existence +message: "Use 'select' instead of the input-specific verb '%s'." +link: https://learn.microsoft.com/en-us/style-guide/procedures-instructions/describing-interactions-with-ui +level: warning +ignorecase: true +# 'right-click' and 'double-click' are explicitly allowed by the guide. +tokens: + - '(? +Fern Agent is in beta and enabled for a limited set of organizations. If the chat panel doesn't appear in your dashboard, Fern Agent isn't enabled for your organization yet. + ## What you can do ### Edit your docs -Ask Fern Agent to make changes to any of your docs sites. It reads your source repository, makes the requested edits, and delivers them as a branch, a pull request, or a live draft in the visual editor — whichever you prefer. +Fern Agent reads your docs site's source repository and makes the changes you describe. It commits them to a new branch and hands the branch to the [Fern Editor](/learn/docs/writing-content/fern-editor) so you can review the draft, then opens a pull request when you ask for one. If you already have the site open in the editor, the changes go into your live draft instead. -Add a new page about authentication to my getting-started guide. +Add a page about authentication to my getting-started guide.
@@ -29,52 +33,66 @@ Move the changelog section to the top of the sidebar. ### Explore analytics -Ask questions about your docs traffic, reader behavior, and broken links without writing a single query. +Fern Agent queries pageviews, visitors, sessions, 404s, referring domains, search queries, reader feedback, and LLM bot traffic for any docs site in your organization. -Which pages got the most traffic last month? +List the pages with the most traffic last month.
- -Are there any 404s on my site? + +List the top 404 paths on my site over the last 30 days.
-Where is my traffic coming from? +Break down last week's traffic by referring domain. -### Review Ask AI activity +### Review Ask Fern activity -Get a summary of what your readers are asking [Ask Fern](/learn/docs/ai-features/ask-fern/overview), which questions went unresolved, and what topics might need better documentation coverage. +Fern Agent summarizes what readers ask [Ask Fern](/learn/docs/ai-features/ask-fern/overview), including resolution rates and individual conversations, so you can find topics that need better coverage. -What have readers been asking about this week? +Summarize what readers asked Ask Fern this week.
-Show me unresolved Ask AI conversations. +List the unresolved Ask Fern conversations. + + +### Review configuration and deployments + +Fern Agent reports a site's deployment history, connected git repository, Fern CLI version, custom domain, and reader-facing settings such as search behavior and password protection. + + +List the recent deployments for docs.plantstore.com. + + +
+ + +List the features enabled on docs.plantstore.com. ### Manage your organization -Ask about members, billing, API keys, and site settings. For actions that require dashboard access, Fern Agent links you directly to the right page. +Fern Agent lists your organization's members and their roles. It can't create API keys, change members, or update billing; for those it links you to the dashboard page that does. -Who are the admins in my organization? +List the admins in my organization.
-Where do I manage API keys? +Open the dashboard page for managing API keys. ## Getting started -Fern Agent is available to all Fern users from the [Dashboard](https://dashboard.buildwithfern.com/). Open the dashboard and use the chat panel to start a conversation. No setup is required. +Open the [Fern Dashboard](https://dashboard.buildwithfern.com/) and start a conversation in the chat panel. No setup is required. diff --git a/fern/products/docs/pages/ai/overview.mdx b/fern/products/docs/pages/ai/overview.mdx index 94232015e3..85e204993e 100644 --- a/fern/products/docs/pages/ai/overview.mdx +++ b/fern/products/docs/pages/ai/overview.mdx @@ -31,9 +31,10 @@ Help users get instant, cited answers from your documentation wherever they're w ## Create and update content -AI helps keep your documentation current. Fern Writer is a Slack-based technical writing agent that creates pull requests with targeted edits when you tag `@Fern Writer` to request updates. For API Reference docs, Fern automatically generates realistic examples from your OpenAPI spec that stay synchronized with spec changes, replacing placeholder values like `"string"` with believable data. +AI helps keep your documentation current. Fern Writer is a Slack-based technical writing agent that creates pull requests with targeted edits when you tag `@Fern Writer` to request updates. Fern Agent works from the Fern Dashboard, where it edits your docs and answers questions about your analytics, readers, and site configuration. For API Reference docs, Fern automatically generates realistic examples from your OpenAPI spec that stay synchronized with spec changes, replacing placeholder values like `"string"` with believable data. - + + From 5507b110956e6a8cb5df1e3ddce685f5e73a0795 Mon Sep 17 00:00:00 2001 From: "devin.logan" Date: Thu, 13 Aug 2026 17:33:04 +0000 Subject: [PATCH 5/7] docs: avoid time-relative wording in the Slack answers section Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> --- fern/products/docs/pages/ai/fern-slack.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/fern/products/docs/pages/ai/fern-slack.mdx b/fern/products/docs/pages/ai/fern-slack.mdx index bc22fa9e35..d6bb651b27 100644 --- a/fern/products/docs/pages/ai/fern-slack.mdx +++ b/fern/products/docs/pages/ai/fern-slack.mdx @@ -82,7 +82,7 @@ Members then see `@YourCompanyName Support was added to the channel` instead of ### Improve answers over time -Teaching the bot from real conversations improves future responses: +Teaching the bot from real conversations improves the answers it gives later: 1. **A member asks a question** - The bot responds in the channel 2. **Review the response** - If the answer needs improvement, reply in the thread to the bot's message @@ -91,7 +91,7 @@ Teaching the bot from real conversations improves future responses: 5. **Iterate if needed** - The bot drafts an improved Q&A pair. Continue refining until it looks right 6. **Confirm indexing** - Tell the bot to save the pair, and it confirms the Q&A pair has been indexed -Once indexed, the curated question-answer pair informs future responses to similar questions. +Once indexed, the curated question-answer pair informs the bot's answers to similar questions. From d215471552e4cf2208556eb98bdc1a654f185c9a Mon Sep 17 00:00:00 2001 From: "devin.logan" Date: Thu, 13 Aug 2026 17:43:54 +0000 Subject: [PATCH 6/7] docs: present Fern in Slack as one bot with two capability categories Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> --- fern/products/docs/pages/ai/fern-slack.mdx | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/fern/products/docs/pages/ai/fern-slack.mdx b/fern/products/docs/pages/ai/fern-slack.mdx index d6bb651b27..ac7400a470 100644 --- a/fern/products/docs/pages/ai/fern-slack.mdx +++ b/fern/products/docs/pages/ai/fern-slack.mdx @@ -4,22 +4,22 @@ description: >- Answer product questions and open documentation pull requests from Slack, without leaving the channel where the conversation happens. --- -Fern brings your documentation into Slack in two ways: a bot that answers questions with cited answers from your docs, and a writing agent that turns a described change into a GitHub pull request. Each capability installs as its own Slack app, so you can add one or both. +`@Fern` brings your documentation into Slack. Tag it in any channel to get cited answers to questions about your product, or ask it to update your docs and it opens a GitHub pull request with the changes. - - Ask a question in any channel and the bot searches your documentation and replies with a cited answer in the thread. + + Ask a question in any channel and Fern searches your documentation and replies with a cited answer in the thread. - + Describe a docs change and Fern opens a GitHub pull request with the edits. Review and iterate in the thread, then merge when ready. -Installing either app in a Slack workspace requires Slack admin access. +Each capability has its own installation, and both require Slack admin access to add to a workspace. ## Answering questions -The Ask Fern bot searches your documentation database and replies in the thread with a cited answer. Questions and answers are stored for [analytics](/learn/docs/ai-features/ask-fern/overview#analytics). +Fern searches your documentation database and replies in the thread with a cited answer. Questions and answers are stored for [analytics](/learn/docs/ai-features/ask-fern/overview#analytics). ### Setup @@ -161,7 +161,7 @@ sequenceDiagram ## Updating docs -The writing agent keeps your docs aligned as your product evolves. It's powered by [Devin from Cognition](https://cognition.ai/blog/introducing-devin), understands Fern components and your writing style, and can be customized with an `AGENTS.md` file in your docs repository. +Docs updates keep your content aligned as your product evolves. This capability is powered by [Devin from Cognition](https://cognition.ai/blog/introducing-devin), understands Fern components and your writing style, and can be customized with an `AGENTS.md` file in your docs repository.