> For the complete documentation index, see [llms.txt](https://docs.aqua-cloud.io/documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.aqua-cloud.io/documentation/aqua-intelligence/knowledge-base-with-aqua-intelligence/best-practices-for-the-knowledge-base-in-aqua.md).

# Best practices for the Knowledge Base in aqua

Getting the most out of aqua Intelligence's knowledge base starts with how you **prepare** and **organise** your files. Since aqua Intelligence retrieves relevant pieces of text from your uploaded documents, clarity and structure directly affect the quality of outputs.

### Prepare focused, well-structured documents

Avoid large all-in-one files. Split documentation by project, product area, feature, or release. Smaller, focused files give aqua Intelligence clearer context to work from.

* **One file, one intent** — for example: *"UI test design patterns for WebApp A"* rather than *"all QA documentation"*
* **Avoid** **mixing** product areas — keep mobile and web requirements in separate files
* **Begin** each file with a short **abstract** (3–5 lines) describing its **purpose**, **scope**, and key entities
* Add a FAQ section where relevant — aqua Intelligence retrieves Q\&A-shaped content particularly well

*Example of a well-organised file set for a checkout feature*

* <mark style="color:$primary;">checkout-acceptance-criteria.docx</mark>
* <mark style="color:$primary;">checkout-api-reference.txt</mark>
* <mark style="color:$primary;">checkout-defect-patterns.docx</mark>

#### Use descriptive file names

File names are included in retrieval metadata. A descriptive name helps aqua Intelligence understand the source context and helps you identify where an answer came from in chat.

**✅ Good examples:**

* <mark style="color:$primary;">login-acceptance-criteria-v1.docx</mark>
* <mark style="color:$primary;">mobile-app-test-strategy.docx</mark>

**❌ Poor examples:**

* <mark style="color:$primary;">doc1.docx</mark>
* <mark style="color:$primary;">Final-version2.docx</mark>

#### Structure your content

* Start with a summary — the first 2–5 sentences should explain what the document covers
* Use headings and subheadings to separate topics
* Use bullet points or numbered lists rather than long paragraphs where possible
* Avoid merged cells, nested tables, or heavy formatting in tables — these can break text extraction
* For important tables, mirror key rules as bullet points below the table to ensure they are retrievable even if the table is not parsed perfectly
* Add a short intro sentence before any table to give aqua Intelligence context before it parses the rows

AI works best when text is easy to parse.

* **Start with a summary.** First 2–5 sentences should explain what the document is about.

> This file contains acceptance criteria for the checkout process, covering payment validation, discounts, and error handling.

* **Use headings and sub-headings to separate topics**

`## Checkout process`

`### Payment validation`

`### Error handling`

* Use bullet **points** or numbered **lists** rather than long paragraphs where possible

**Example**:

> * <mark style="color:$primary;">User must be logged in before starting checkout</mark>
> * <mark style="color:$primary;">System validates credit card number format</mark>
> * <mark style="color:$primary;">Discounts cannot exceed total order value</mark>

#### Keep your documents in one language

If your team works in multiple languages, use one language per file or per document set. Mixing languages in the same file can reduce retrieval accuracy.

#### Version your documents

Documentation changes over time. To keep aqua Intelligence working from current material:

* Include version numbers in file names: `checkout-acceptance-criteria-v2.docx`
* Re-upload updated files when documentation changes
* Delete or archive outdated versions so they are no longer used for generation

### Best practices with tables

* Keep tables simple if possible
* Use plain rows and columns with clear headers.
* Avoid merged cells, heavy formatting, or nested tables — they often break the text extraction.
* Try to include headers
* Mirror table content in text if it’s crucial for grounding or If the table contains important rules, write them out below as bullet points.

**Example:**

> <mark style="color:$primary;">Empty password → show error “Password required”</mark> &#x20;
>
> <mark style="color:$primary;">Password too short → show error “Minimum 8 characters”</mark> &#x20;
>
> <mark style="color:$primary;">Valid password → allow login</mark> &#x20;

This ensures the AI can retrieve the info even if the table isn’t parsed perfectly.

* Split big tables into smaller ones if applicable
* Large, complex tables (e.g., covering 50+ scenarios) are harder for AI to process.
* Break them down by feature, rule set, or risk area.
* Add a short intro sentence before the table. This gives AI context before parsing rows.

**Example:**&#x20;

> <mark style="color:$primary;">The following table lists password validation scenarios with expected outcomes.</mark>

### Write effective descriptions when generating

When you select **Description** you’re telling aqua Intelligence what context it should use when generating your test cases, user story or test data. Think of it as a requirement ticket: the clearer and more structured, the better the results. Don't use ambigious wording. Try to be as clear as possible.

*💡 Tip: Pretend you’re briefing a* *new colleague that is not familiar with domain context*. *If they could design test cases or write a requirement from what you write, it’s a good description for AI too.*

#### A good description includes

* **Feature / area under test**\
  “User login with email and password, including validation of mandatory fields and error messages.”
* **Scope and boundaries**\
  “Covers positive login attempts with valid credentials and negative cases for wrong passwords and empty fields.'
* **Intended outcome**\
  “System must display error messages clearly and prevent login with invalid data.”
* **Optional keywords** (important terms that should appear in test cases)\
  “Include cases with minimum/maximum password length.”

#### Examples of good vs poor descriptions

**✅ Good:**

> Checkout process for registered users, including adding items to cart, applying a discount code, and completing payment via credit card. Verify both successful and failed payment scenarios.

**❌ Poor:**

> After completing the checkout process, everything must be verified before proceeding.\
> If that fails, restart the task.

**✅ Good:**

> Mobile app login using biometric authentication (fingerprint/face ID). Test positive login, fallback to PIN, and failed authentication attempts. If the session verification fails, restart the authentication workflow.

**❌ Poor:**

> Cover the full login process with successful and failed attempts

***

#### Use explicit language — avoid ambiguous references

Phrases like "this", "that", or "the process" make it unclear what is being described. Use explicit nouns instead.

❌ *"This should be validated before continuing."*

✅ *"The checkout form should be validated before continuing."*

#### Maintain consistent terminology

The same concept often appears under different names — for example *login*, *sign-in*, and *authentication*. If you want aqua Intelligence to treat these as equivalent, add a terminology mapping or alias dictionary to your documents.

* Example:

  ```
  login = sign-in = authentication
  cart = basket
  ```

Use this dictionary across your documents so both the system and readers understand the intended meaning.

### Quick checklist before generating

1. Have you specified the feature or area under test?
2. Have you included special conditions (limits, error handling, edge cases)?
3. Is your description at least 2–3 sentences?
4. Have you uploaded files current and relevant to this generation task?

If yes, then you are good to go :thumbsup:


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.aqua-cloud.io/documentation/aqua-intelligence/knowledge-base-with-aqua-intelligence/best-practices-for-the-knowledge-base-in-aqua.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.