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

• checkout-acceptance-criteria.docx

• checkout-api-reference.txt

• checkout-defect-patterns.docx

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:

• login-acceptance-criteria-v1.docx

• mobile-app-test-strategy.docx

❌ Poor examples:

• doc1.docx

• Final-version2.docx

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:

• User must be logged in before starting checkout

• System validates credit card number format

• Discounts cannot exceed total order value

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:

Empty password → show error “Password required”

Password too short → show error “Minimum 8 characters”

Valid password → allow login

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:

The following table lists password validation scenarios with expected outcomes.

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 👍