A docs assistant is useful when a reader can understand where its answer came from. The reader asks a direct question. The assistant looks only at the published documentation, answers from the relevant pages, and cites those pages so the reader can check the surrounding context.
That boundary is the important part. The assistant is another way into the documentation. It gives a reader a shorter path to an answer while keeping the published pages as the source of truth.
When those pages lack the answer, the assistant says so plainly. That response protects reader trust and gives the team a concrete signal that the documentation needs another page or a clearer explanation.
A question begins with the published docs
The assistant works from the same material a reader can open on the site. A question such as How do I rotate an API key? is matched against the published pages. The answer uses the relevant passages and includes links back to them.
The exact interface can vary, but the exchange can be represented by a simple request:
curl https://docs.example.com/ask \
--header 'content-type: application/json' \
--data '{"question":"How do I rotate an API key?"}'The response keeps the answer and its supporting pages together:
{
"answer": "Create a replacement key, update the application that uses it, then revoke the old key.",
"citations": [
{
"title": "Rotate an API key",
"url": "/security/rotate-api-key/"
},
{
"title": "Revoke an API key",
"url": "/security/revoke-api-key/"
}
]
}The example is deliberately ordinary. The answer is concise, and the citations carry the reader to the full procedure. A short response can solve the immediate problem. The pages still hold prerequisites, warnings, examples, and related details.
Why the source boundary matters
Readers should be able to predict what kind of answer they are receiving. Restricting the assistant to published documentation creates a clear boundary around the available evidence.
That boundary helps in three ways:
- The answer reflects material the team has chosen to publish.
- The citations let a reader verify the wording and read more context.
- A missing answer exposes a documentation gap instead of filling it with a guess.
This is especially important for details that change, such as configuration fields or authentication steps. The page can be updated when the product changes. Future answers then draw from the revised source.
Citations make the answer inspectable
A citation is a functional part of the answer. It tells the reader which page supports a statement and gives them a direct route to the complete instructions.
For a practical question, the relationship might look like this:
| Reader asks | Answer draws from | Reader can verify |
|---|---|---|
| How do I create a key? | Key setup guide | Required fields |
| Can I revoke a key? | Security guide | Revocation steps |
| Which errors can occur? | API reference | Status and error details |
The assistant may use more than one page when the question crosses a boundary. For example, a setup guide may explain the workflow while an API reference supplies an exact request field. Listing both pages makes that combination visible.
The page remains the durable answer
The published page is where the team can make a complete statement. It can explain order, exceptions, and consequences with enough room for a reader to understand the task. It also has a stable location that people and software can cite later.
The assistant provides a focused response for the question in front of it. Its citations reconnect that response to the durable material. Readers who need one step can move quickly. Readers who need the whole procedure can open the page.
An unanswered question becomes a documentation task
Some questions arrive before the documentation covers them. In that case, a trustworthy response is direct: the published docs do not contain enough information to answer.
A simplified response can make the limit explicit:
{
"answer": "The published documentation does not cover this question yet.",
"citations": []
}The unanswered question then becomes input for the SaturnDocs agents. They inspect the gap, ask the product team for missing context when needed, and write or revise the appropriate page. Once that page is published, the documentation contains an answer the assistant can cite.
A useful feedback loop
The loop stays simple. A reader asks. The assistant answers from the docs or identifies a gap. The team improves the source. Later readers receive the stronger documentation through both the page and the assistant.
This approach treats uncertainty as useful information. It preserves trust in the current answer and shows where the documentation can become more complete. The result is an assistant that helps readers navigate what is known while helping the team see what should be written next.
This is the model behind the SaturnDocs AI assistant: answers stay grounded in the published pages, citations remain visible, and unanswered questions become specific documentation work.