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 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 -``` -