Skip to content

Commit 5ce4a86

Browse files
devalogeyw520
devalog
and
eyw520
authored
Expand Ask Fern documentation (#444)
Co-authored-by: eden <[email protected]> Co-authored-by: eden <[email protected]>
1 parent 6c473ed commit 5ce4a86

File tree

10 files changed

+168
-31
lines changed

10 files changed

+168
-31
lines changed

‎fern/apis/fai/definition/commons.yml‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,3 +7,10 @@ errors:
77
InternalError:
88
status-code: 401
99
type: string
10+
11+
types:
12+
Pagination:
13+
properties:
14+
total: integer
15+
page: integer
16+
limit: integer

‎fern/apis/fai/definition/document.yml‎

Lines changed: 54 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -40,7 +40,59 @@ service:
4040
authed:
4141
type: optional<boolean>
4242
docs: Whether the document is authed
43-
response: CreateDocumentResponse
43+
response: DocumentIdResponse
44+
errors:
45+
- commons.BadRequestError
46+
- commons.InternalError
47+
48+
updateDocument:
49+
docs: Update a document for a given domain
50+
path: /{domain}/{document_id}
51+
method: PATCH
52+
audiences:
53+
- customers
54+
path-parameters:
55+
domain: string
56+
document_id: string
57+
request:
58+
name: UpdateDocumentRequest
59+
body:
60+
properties:
61+
document:
62+
type: optional<string>
63+
docs: The content of the document that will be returned in the tool response.
64+
chunk:
65+
type: optional<string>
66+
docs: The chunk of the document that will be indexed as a vector.
67+
title:
68+
type: optional<string>
69+
docs: The title of the document
70+
url:
71+
type: optional<string>
72+
docs: The url of the document
73+
version:
74+
type: optional<string>
75+
docs: The version of the document
76+
keywords:
77+
type: optional<list<string>>
78+
docs: The keywords of the document
79+
authed:
80+
type: optional<boolean>
81+
docs: Whether the document is authed
82+
response: Document
83+
errors:
84+
- commons.BadRequestError
85+
- commons.InternalError
86+
87+
deleteDocumentById:
88+
docs: Delete a document for a given domain
89+
path: /{domain}/{document_id}
90+
method: DELETE
91+
audiences:
92+
- customers
93+
path-parameters:
94+
domain: string
95+
document_id: string
4496
errors:
4597
- commons.BadRequestError
4698
- commons.InternalError
@@ -60,7 +112,7 @@ service:
60112
- commons.InternalError
61113

62114
types:
63-
CreateDocumentResponse:
115+
DocumentIdResponse:
64116
properties:
65117
document_id: string
66118

‎fern/apis/fai/definition/guidance.yml‎

Lines changed: 6 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,7 @@ service:
2525
document:
2626
type: string
2727
docs: The content of the guidance document that will be returned in the tool response
28+
response: GuidanceIdResponse
2829
errors:
2930
- commons.BadRequestError
3031
- commons.InternalError
@@ -101,6 +102,10 @@ service:
101102
- commons.InternalError
102103

103104
types:
105+
GuidanceIdResponse:
106+
properties:
107+
guidance_id: string
108+
104109
Guidance:
105110
properties:
106111
guidance_id: string
@@ -113,10 +118,4 @@ types:
113118
GuidanceList:
114119
properties:
115120
guidances: list<Guidance>
116-
pagination: Pagination
117-
118-
Pagination:
119-
properties:
120-
total: integer
121-
page: integer
122-
limit: integer
121+
pagination: commons.Pagination

‎fern/products/ask-fern/ask-fern.yml‎

Lines changed: 8 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -13,8 +13,14 @@ navigation:
1313
contents:
1414
- page: Citations
1515
path: ./pages/features/citations.mdx
16-
- page: Custom FAQs
17-
path: ./pages/features/custom-faqs.mdx
16+
- page: Custom Guidance
17+
path: ./pages/features/guidance.mdx
18+
- page: Custom Documents
19+
path: ./pages/features/documents.mdx
20+
- page: Insights
21+
path: ./pages/features/insights.mdx
22+
- page: Evaluation
23+
path: ./pages/features/evals.mdx
1824
- api: API reference
1925
api-name: fai
2026
icon: fa-regular fa-pro

‎fern/products/ask-fern/pages/features/custom-faqs.mdx‎

Lines changed: 0 additions & 10 deletions
This file was deleted.

‎fern/products/ask-fern/pages/features/documents.mdx‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
---
2+
title: Documents
3+
subtitle: Add arbitrary documents to Ask Fern.
4+
---
5+
6+
You can add arbitrary documents to Ask Fern. This is useful for adding additional content that may improve Ask Fern's accuracy
7+
(such as help desk tickets, internal company FAQs, etc.).
8+
9+
Fern offers an internal CMS (content management system) via the `documents` API that allows you to add, update,
10+
and delete documents as needed.

‎fern/products/ask-fern/pages/features/evals.mdx‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
---
2+
title: Evals
3+
description: Benchmark Ask Fern's accuracy against your documentation.
4+
---
5+
6+
<Markdown src="/snippets/wip-callout.mdx" />
7+
8+
Fern evaluates how accurately Ask Fern answers questions on your documentation site compared to competitor AI search solutions.
9+
10+
Fern first generates evaluation questions from your documentation files, then runs those questions through both Ask Fern and competitor systems.
11+
Finally, Fern evaluates each answer against the original documentation for accuracy. You receive detailed performance metrics and comparative analysis.
12+
13+
## Availability
14+
15+
Evals are currently provided as custom analysis delivered directly by the Fern team.

‎fern/products/ask-fern/pages/features/guidance.mdx‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
---
2+
title: Custom Guidance
3+
subtitle: Fine-tune your AI search responses.
4+
---
5+
6+
You can add custom guidance (FAQs) to "override" Ask Fern's responses to specific user queries.
7+
This is useful for content that you may not wish to display publically, such as billing information,
8+
legal terms, and other sensitive content.
9+
10+
Fern offers an internal CMS (content management system) via the `guidance` API that allows you to add,
11+
update, and delete FAQs as needed.

‎fern/products/ask-fern/pages/features/insights.mdx‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
---
2+
title: Insights
3+
description: Fern identifies documentation gaps and improvement opportunities from your user queries.
4+
---
5+
6+
<Markdown src="/snippets/wip-callout.mdx" />
7+
8+
Fern analyzes Ask Fern query patterns to surface actionable recommendations for improving your documentation. After collecting sufficient query data over a month, Fern processes this through specialized models that analyze query-response pairs to identify documentation gaps, extract common themes, and generate specific suggestions for enhancing your docs.
9+
10+
## Availability
11+
12+
Insights are currently provided as a monthly report delivered directly by the Fern team.

‎fern/products/ask-fern/pages/getting-started/what-is-ask-fern.mdx‎

Lines changed: 45 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,21 @@
11
---
2-
title: AI Search Overview
2+
title: What is Ask Fern?
33
subtitle: Let your customers find answers in your documentation instantly.
44
---
55

6+
<Note>Ask Fern is available on the [Pro plan](https://buildwithfern.com/pricing#Docs) of Fern Docs. Billing is by usage.</Note>
7+
68
## Overview
79

810
<Frame caption="AI Search is accessed via the search bar, alongside keyword search.">
911
<img src="../assets/search-modal.png" alt="Accessing AI Search" />
1012
</Frame>
1113

12-
Fern AI Search indexes your documentation and provides an interface for your users to ask questions and get answers. We've found that it helps our customers:
14+
Ask Fern is Fern's AI Search feature that indexes your documentation and provides an interface for your users to ask questions and get answers. It helps our customers
1315

14-
- **Decrease the time to find needed information** - Help users quickly locate crucial documentation without navigating through a maze of tabs and endpoints.
15-
- **Integrate your product faster** - Accelerate implementation with ready-to-use code samples that demonstrate practical applications.
16-
- **Surface where your docs have gaps** - Identify documentation weaknesses through user feedback and search patterns.
16+
- **Decrease the time to find needed information** – Help users quickly locate crucial documentation without navigating through a maze of tabs and endpoints.
17+
- **Integrate your product faster** – Accelerate implementation with ready-to-use code samples that demonstrate practical applications.
18+
- **Surface where your docs have gaps** – Identify documentation weaknesses through user feedback and search patterns.
1719

1820
<Frame caption="Users can ask questions and get support in an intuitive chat interface.">
1921
<img src="../assets/ask-ai-modal.png" alt="Preview of AI Search" />
@@ -27,7 +29,7 @@ Fern AI Search indexes your documentation and provides an interface for your use
2729
icon="regular book-open"
2830
href="/learn/ai-search/custom-prompting"
2931
>
30-
Tailor AI Search results to your users' needs.
32+
Tailor Ask Fern results to your users' needs.
3133
</Card>
3234

3335
<Card
@@ -43,19 +45,52 @@ Fern AI Search indexes your documentation and provides an interface for your use
4345
icon="regular plug"
4446
href="/learn/docs/building-and-customizing-your-docs/search"
4547
>
46-
Offer flexibility to have users 'Ask AI' or search your docs directly with Algolia.
48+
Offer flexibility to have users "Ask AI" or search your docs directly with Algolia.
4749
</Card>
4850

4951
<Card
5052
title="All-in-one platform"
5153
icon="regular fa-layer-group"
5254
href="/learn/docs/getting-started/overview"
5355
>
54-
Create seamless UX by offering a 'one-stop-shop' for all docs questions.
56+
Create seamless UX by offering a one-stop-shop for all docs questions.
5557
</Card>
5658

5759
</CardGroup>
5860

59-
## Pricing
61+
## How it works
62+
63+
Ask Fern is a **Retrieval Augmented Generation (RAG)** system built on top of your documentation site that transforms your documentation into an intelligent, searchable knowledge base. The main parts of the Ask Fern system are:
64+
65+
* **Content indexing** – Fern automatically processes your documentation pages,
66+
breaking them into semantic chunks and converting each chunk into a vector
67+
using sentence embedding models. They're stored in a database that serves as
68+
Ask Fern's search index.
69+
* **Query processing** – When users ask questions, Ask Fern vectorizes their
70+
query and searches the database to find the most relevant documentation
71+
chunks.
72+
* **Response generation** – Ask Fern uses the retrieved chunks as context to
73+
generate accurate answers with [citations](/ask-fern/features/citations) for the user. If the initial context isn't sufficient, it performs an additional keyword search.
74+
75+
### Life of a query
76+
77+
Each Ask Fern user query follows these steps:
6078

61-
Ask Fern is available on the [Pro plan](https://buildwithfern.com/pricing#Docs) of Fern Docs. Billing is by usage.
79+
```mermaid
80+
sequenceDiagram
81+
autonumber
82+
participant U as User
83+
participant C as /chat Endpoint
84+
participant V as Documentation Database
85+
participant A as Ask Fern
86+
87+
U->>C: Submit question via Ask Fern searchbox
88+
C->>C: Convert query to vector
89+
C->>V: Search for relevant chunks
90+
V->>C: Return matching documents
91+
C->>A: Send query + context
92+
A->>V: Perform additional keyword search if needed
93+
V->>A: Return additional chunks
94+
A->>A: Generate response
95+
A->>U: Return answer with citations
96+
```

0 commit comments

Comments
 (0)