From b240154159049033e505f1ef339e3371ee93c9ca Mon Sep 17 00:00:00 2001 From: eden Date: Wed, 20 Aug 2025 12:48:57 -0400 Subject: [PATCH 1/4] feat(docs): Add `Guidance` and `Documents` guides to Ask Fern docs. --- fern/apis/fai/definition/document.yml | 28 ++++++++++- fern/apis/fai/definition/guidance.yml | 3 +- fern/products/ask-fern/ask-fern.yml | 11 ++--- .../ask-fern/pages/features/documents.mdx | 21 +++++++-- .../ask-fern/pages/features/guidance.mdx | 46 +++++++++++++++++-- .../getting-started/what-is-ask-fern.mdx | 22 +++++++-- 6 files changed, 112 insertions(+), 19 deletions(-) diff --git a/fern/apis/fai/definition/document.yml b/fern/apis/fai/definition/document.yml index 8cfe442b3..391390bae 100644 --- a/fern/apis/fai/definition/document.yml +++ b/fern/apis/fai/definition/document.yml @@ -8,7 +8,8 @@ service: base-path: /document endpoints: createDocument: - docs: Index a document for a given domain + docs: | + Index a document for a given domain. Documents can be used to provide additional context to Ask Fern and improve its accuracy. path: /{domain}/create method: POST audiences: @@ -111,6 +112,26 @@ service: - commons.BadRequestError - commons.InternalError + getDocuments: + docs: Retrieve all paginated documents for a given domain + path: /{domain} + method: GET + audiences: + - customers + path-parameters: + domain: + type: string + docs: The domain to retrieve documents for + request: + name: GetDocumentsRequest + query-parameters: + page: optional + limit: optional + response: DocumentList + errors: + - commons.BadRequestError + - commons.InternalError + types: DocumentIdResponse: properties: @@ -129,3 +150,8 @@ types: authed: optional created_at: datetime updated_at: datetime + + DocumentList: + properties: + documents: list + pagination: commons.Pagination diff --git a/fern/apis/fai/definition/guidance.yml b/fern/apis/fai/definition/guidance.yml index 03798c69e..9f4af5143 100644 --- a/fern/apis/fai/definition/guidance.yml +++ b/fern/apis/fai/definition/guidance.yml @@ -8,7 +8,8 @@ service: base-path: /guidance endpoints: createGuidance: - docs: Index a guidance document for a given domain + docs: | + Create a guidance for a given domain. Guidance can be used to provide additional context to Ask Fern and improve its accuracy. path: /{domain}/create method: POST audiences: diff --git a/fern/products/ask-fern/ask-fern.yml b/fern/products/ask-fern/ask-fern.yml index e25b370eb..42e2acd04 100644 --- a/fern/products/ask-fern/ask-fern.yml +++ b/fern/products/ask-fern/ask-fern.yml @@ -7,23 +7,22 @@ navigation: href: https://buildwithfern.com/showcase#ask-fern-customers - section: Configuration contents: - - page: Custom prompting + - page: Custom prompts path: ./pages/configuration/custom-prompting.mdx + - page: Guidance + path: ./pages/features/guidance.mdx + - page: Documents + path: ./pages/features/documents.mdx - section: Features contents: - page: Citations path: ./pages/features/citations.mdx - - page: Custom Guidance - path: ./pages/features/guidance.mdx - - page: Custom Documents - path: ./pages/features/documents.mdx - page: Insights path: ./pages/features/insights.mdx - page: Evaluation path: ./pages/features/evals.mdx - api: API reference api-name: fai - icon: fa-regular fa-pro paginated: true audiences: - customers diff --git a/fern/products/ask-fern/pages/features/documents.mdx b/fern/products/ask-fern/pages/features/documents.mdx index 21a413551..693ec6cfa 100644 --- a/fern/products/ask-fern/pages/features/documents.mdx +++ b/fern/products/ask-fern/pages/features/documents.mdx @@ -1,10 +1,25 @@ --- title: Documents -subtitle: Add arbitrary documents to Ask Fern. +subtitle: Add custom data sources to Ask Fern. --- -You can add arbitrary documents to Ask Fern. This is useful for adding additional content that may improve Ask Fern's accuracy -(such as help desk tickets, internal company FAQs, etc.). +You can index custom documents to Ask Fern beyond your documentation. This is useful for adding additional content that may improve Ask Fern's ability +to support developers, such as help desk tickets, internal company FAQs, etc. Fern offers an internal CMS (content management system) via the `documents` API that allows you to add, update, and delete documents as needed. + +## Usage + +Here's an example of a document that can be uploaded via the `documents` API: + +```json +{ + "document": "Ferns are plants native to the tropical and subtropical regions of the world. They are characterized by their fronds, which are large, leaf-like structures that are often found in the understory of forests.", + "title": "What are ferns?", + "url": "https://en.wikipedia.org/wiki/Fern" +} +``` + +This document will be indexed and made available to Ask Fern as context when users ask questions about ferns. + diff --git a/fern/products/ask-fern/pages/features/guidance.mdx b/fern/products/ask-fern/pages/features/guidance.mdx index adba04374..0f99e17c6 100644 --- a/fern/products/ask-fern/pages/features/guidance.mdx +++ b/fern/products/ask-fern/pages/features/guidance.mdx @@ -1,11 +1,47 @@ --- title: Custom Guidance -subtitle: Fine-tune your AI search responses. +subtitle: Fine-tune your Ask Fern responses. --- -You can add custom guidance (FAQs) to "override" Ask Fern's responses to specific user queries. -This is useful for content that you may not wish to display publically, such as billing information, -legal terms, and other sensitive content. +## Overview + +You can add custom guidance to "override" Ask Fern's responses to specific user queries. This is useful for content that you +may not want to display explicitly in your documentation, such as billing information, legal terms, and other sensitive content. + +Guidance documents consist of a list of `context` texts and a `document` text. The `context` texts will be indexed +to match against user queries. The `document` text will used as a prescribed response to the user query. + +## API Fern offers an internal CMS (content management system) via the `guidance` API that allows you to add, -update, and delete FAQs as needed. \ No newline at end of file +update, and delete guidance as needed. You will need to provide your `domain` to specify which deployment of Ask Fern +the updates will be applied to. + +## Usage + +Below is an example of a guidance document that can be uploaded via the `guidance` API: + +```json +{ + "context": [ + "Who's our favorite engineer at Fern?", + "Who's the best dog!" + ], + "document": "Jack!" +} +``` + +During the retrieval step, when users ask questions that fuzzy-match against any of the `context` texts, the `document` text will be returned +in the tool response and provided to the Agent as context in the form: + +``` + +In response to the following query: +Who's our favorite engineer at Fern? + +You will return an answer based on the following guidance: +Jack! + +``` + +Ask Fern prioritizes guidance response over other document responses, allowing you to override the default RAG responses. diff --git a/fern/products/ask-fern/pages/getting-started/what-is-ask-fern.mdx b/fern/products/ask-fern/pages/getting-started/what-is-ask-fern.mdx index f5e645a0e..fa08c433c 100644 --- a/fern/products/ask-fern/pages/getting-started/what-is-ask-fern.mdx +++ b/fern/products/ask-fern/pages/getting-started/what-is-ask-fern.mdx @@ -29,7 +29,7 @@ Ask Fern is Fern's AI Search feature that indexes your documentation and provide icon="regular book-open" href="/learn/ai-search/custom-prompting" > - Tailor Ask Fern results to your users' needs. + Tailor Ask Fern behavior to your users' needs. + + Add custom FAQs to Ask Fern. + + + + Add custom documents to Ask Fern. + + - Offer flexibility to have users "Ask AI" or search your docs directly with Algolia. + Users can "Ask AI" or search your docs directly with Algolia. - Create seamless UX by offering a one-stop-shop for all docs questions. + Create seamless UX by offering a one-stop-shop for all API questions. From aed7534c141195a6e872ddfef54d3a00eca7756d Mon Sep 17 00:00:00 2001 From: eden Date: Wed, 20 Aug 2025 13:38:07 -0400 Subject: [PATCH 2/4] update guidance example --- fern/products/ask-fern/pages/features/guidance.mdx | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/fern/products/ask-fern/pages/features/guidance.mdx b/fern/products/ask-fern/pages/features/guidance.mdx index 0f99e17c6..22184ba87 100644 --- a/fern/products/ask-fern/pages/features/guidance.mdx +++ b/fern/products/ask-fern/pages/features/guidance.mdx @@ -24,10 +24,10 @@ Below is an example of a guidance document that can be uploaded via the `guidanc ```json { "context": [ - "Who's our favorite engineer at Fern?", - "Who's the best dog!" + "What billing options are available for enterprise customers with 10-50 seats?", + "How do I upgrade the number of seats for my enterprise plan?" ], - "document": "Jack!" + "document": "Please reach out to support@yourcompany.com for more information." } ``` @@ -37,10 +37,10 @@ in the tool response and provided to the Agent as context in the form: ``` In response to the following query: -Who's our favorite engineer at Fern? +What billing options are available for enterprise customers with 10-50 seats? You will return an answer based on the following guidance: -Jack! +Please reach out to support@yourcompany.com for more information. ``` From e56294a94e837a3d7063d8089449d03b61a8dcf7 Mon Sep 17 00:00:00 2001 From: eden Date: Wed, 20 Aug 2025 13:40:09 -0400 Subject: [PATCH 3/4] Link to API reference --- fern/products/ask-fern/pages/features/documents.mdx | 2 ++ fern/products/ask-fern/pages/features/guidance.mdx | 2 ++ 2 files changed, 4 insertions(+) diff --git a/fern/products/ask-fern/pages/features/documents.mdx b/fern/products/ask-fern/pages/features/documents.mdx index 693ec6cfa..b41888ff1 100644 --- a/fern/products/ask-fern/pages/features/documents.mdx +++ b/fern/products/ask-fern/pages/features/documents.mdx @@ -9,6 +9,8 @@ to support developers, such as help desk tickets, internal company FAQs, etc. Fern offers an internal CMS (content management system) via the `documents` API that allows you to add, update, and delete documents as needed. +See the [API reference](/learn/ask-fern/api-reference/document/create-document) for more details + ## Usage Here's an example of a document that can be uploaded via the `documents` API: diff --git a/fern/products/ask-fern/pages/features/guidance.mdx b/fern/products/ask-fern/pages/features/guidance.mdx index 22184ba87..66b7d0424 100644 --- a/fern/products/ask-fern/pages/features/guidance.mdx +++ b/fern/products/ask-fern/pages/features/guidance.mdx @@ -17,6 +17,8 @@ Fern offers an internal CMS (content management system) via the `guidance` API t update, and delete guidance as needed. You will need to provide your `domain` to specify which deployment of Ask Fern the updates will be applied to. +See the [API reference](/learn/ask-fern/api-reference/guidance/create-guidance) for more details. + ## Usage Below is an example of a guidance document that can be uploaded via the `guidance` API: From bf33eb9539e922f20018b39b04c95dbd9a627ec5 Mon Sep 17 00:00:00 2001 From: eden <64514273+eyw520@users.noreply.github.com> Date: Wed, 20 Aug 2025 13:40:29 -0400 Subject: [PATCH 4/4] Update fern/products/ask-fern/pages/features/documents.mdx Co-authored-by: Devin Logan --- fern/products/ask-fern/pages/features/documents.mdx | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/fern/products/ask-fern/pages/features/documents.mdx b/fern/products/ask-fern/pages/features/documents.mdx index b41888ff1..49780d06c 100644 --- a/fern/products/ask-fern/pages/features/documents.mdx +++ b/fern/products/ask-fern/pages/features/documents.mdx @@ -3,8 +3,7 @@ title: Documents subtitle: Add custom data sources to Ask Fern. --- -You can index custom documents to Ask Fern beyond your documentation. This is useful for adding additional content that may improve Ask Fern's ability -to support developers, such as help desk tickets, internal company FAQs, etc. +You can index custom documents beyond your core documentation to improve Ask Fern's capabilities. Adding content such as help desk tickets, internal company FAQs, and other resources can help provide better answers to developers. Fern offers an internal CMS (content management system) via the `documents` API that allows you to add, update, and delete documents as needed.