feat(docs): Add Guidance and Documents guides to Ask Fern docs.

eyw520 · eyw520 · commit b24015415904 · 2025-08-20T12:48:57.000-04:00
diff --git 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<integer>
+          limit: optional<integer>
+      response: DocumentList
+      errors:
+        - commons.BadRequestError
+        - commons.InternalError
+
 types:
   DocumentIdResponse:
     properties:
@@ -129,3 +150,8 @@ types:
       authed: optional<boolean>
       created_at: datetime
       updated_at: datetime
+  
+  DocumentList:
+    properties:
+      documents: list<Document>
+      pagination: commons.Pagination
diff --git 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
@@ -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
@@ -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
@@ -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. 
+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:
+
+```
+<GUIDANCE>
+In response to the following query:
+Who's our favorite engineer at Fern?
+
+You will return an answer based on the following guidance:
+Jack!
+</GUIDANCE>
+```
+
+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
@@ -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. 
   </Card>
 
   <Card 
@@ -40,20 +40,36 @@ Ask Fern is Fern's AI Search feature that indexes your documentation and provide
     Point users to the exact source of the answer. 
   </Card>
 
+  <Card 
+    title="Guidance" 
+    icon="regular fa-question-circle"
+    href="/learn/ask-fern/features/guidance" 
+    >
+    Add custom FAQs to Ask Fern. 
+  </Card>
+
+  <Card 
+    title="Documents" 
+    icon="regular file-alt"
+    href="/learn/ask-fern/features/documents" 
+    >
+    Add custom documents to Ask Fern. 
+  </Card>
+
   <Card 
     title="Integration with Algolia" 
     icon="regular plug"
     href="/learn/docs/building-and-customizing-your-docs/search" 
     >
-    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. 
   </Card>
 
   <Card 
     title="All-in-one platform" 
     icon="regular fa-layer-group"
     href="/learn/docs/getting-started/overview"
   >
-    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. 
   </Card>
 
 </CardGroup>
