Crafter.ai
Back to documentation

Guidelines for Structuring Documents (RAG)

Ultimo aggiornamento: 12/3/2025

Guidelines for Structuring Documents for Crafter.ai Introduction The following guidelines are designed to optimize the structure of documents to be used...

guidelines RAG documents in crafter.aistructuring RAG Documents

Guidelines for Structuring Documents for Crafter.ai

Introduction

The following guidelines are designed to optimize the structure of documents to be used with the Crafter.ai platform. By leveraging the principles of clarity and structuring, it is possible to drastically improve the effectiveness of its Document Management functionality and the quality of the generated responses.

The goal is to make documents "Crafter.ai-friendly": easy to index and search for the internal Retrieval system and, once found, easy to interpret and use for the platform's Generation engine.

Principle of Modularity and Single Responsibility

Key Concept: The Crafter.ai platform performs better when documents are granular and focused. A document that attempts to cover too many disparate topics in a disorganized manner is difficult to index correctly and to "understand" for the system.

Best Practices Principle of Modularity and Single Responsibility:

  • One Concept per Section: Structure the document so that each section (delimited by an H2 or H3 title) addresses a single topic, concept, or specific question.
  • Focused Files: For very broad and complex topics, consider breaking them down into multiple distinct files. For example, instead of a single file Manual_Product.pdf, you might have Installation.md, Troubleshooting.md, and Advanced_Features.md. This drastically improves retrieval accuracy.
  • Self-Contained Paragraphs: Each paragraph should ideally express a complete idea and start with a topic sentence that summarizes its content.

Hierarchy and Explicit Structure

Key Concept: Crafter.ai interprets documents more effectively when they present a clear and hierarchical structure. A well-formatted document provides a map of information that the system can navigate and use to build precise responses.

Best Practices Hierarchy and Explicit Structure:

  • Correct Use of Headings: Use heading tags (H1, H2, H3, etc.) in a hierarchical and consistent manner.
  • Bullet and Numbered Lists: For processes, feature lists, or steps, use bullet or numbered lists. This formatting "breaks" the text and presents information in an easily digestible format.
  • Tables for Structured Data: If you need to present comparative or tabular data, use tables in Markdown format. They are much more effective than a textual description.

Example Structure:

Guide to Feature X

2.1. Overview

Brief description of what Feature X does.

2.2. System Requirements

  • Operating System: Windows 11, macOS 13+
  • RAM: Minimum 8GB

2.3. Setup Procedure

  1. Open the Settings panel.
  2. Navigate to the "Integrations" section.
  3. Enter the API key...

Clarity of Content and Zero Ambiguity

Key Concept: The accuracy of Crafter.ai directly depends on the clarity of the source documents. The text must be as direct and unambiguous as possible to avoid misinterpretations by the system.

Best Practices Clarity of Content and Zero Ambiguity:

  • Direct Language: Write simple and direct sentences. Avoid complex constructions, overly metaphorical language, or unnecessary jargon.
    • ✅ Example (What to do): "To activate the feature, click the 'Save' button."
    • ❌ Example (What not to do): "The activation of the aforementioned feature is contingent upon the user's interaction with the graphical element designated for data saving."
  • Explicit Definitions: Define all acronyms and technical terms the first time they appear.
    • ✅ Example (What to do): "Our system uses a command-line interface (CLI) for advanced operations."
    • ❌ Example (What not to do): "For advanced operations, you need to use the CLI."
  • Terminological Consistency: Always use the same term to refer to the same concept within the document and, ideally, throughout the knowledge base.
    • ✅ Example (What to do): "Open the User Panel. From the User Panel, you can change the password."
    • ❌ Example (What not to do): "Open the User Panel. From the Client Dashboard, you can change the password."

Enrichment with Metadata (Front Matter)

Key Concept: Providing Crafter.ai with complete context is essential. Metadata at the beginning of a file serves as "context at a glance," helping both the search system and the generation engine to immediately understand what the document is about.

Best Practices (Front Matter):

  • Add Front Matter: Start your documents (especially if in Markdown format) with a block of metadata in YAML format.
  • Useful Fields: Include fields such as title, version, last_updated, author, tags (keywords), and a brief summary. Tags are particularly powerful for improving information retrieval.

Example of YAML Front Matter:

---
title: API Configuration Guide
version: 2.1
last_updated: 2025-10-08
author: Mario Rossi
tags: [api, configuration, backend, security]
summary: This document explains how to configure and secure API endpoints for the production environment.
---

# Document Title
...

Notes

(1) In Markdown files, heading levels are defined by the hash character (#). A single hash defines the main title (H1 = # Title), two hashes define a first-level subtitle (H2 = ## Subtitle), and so on.

Appendix: Working with Markdown Files (.md)

What is a Markdown File?

A Markdown file (with a .md extension) is a simple text file. Its strength lies in the ability to add formatting (such as headings, bold, lists) using easy-to-type characters. It is a much lighter and more manageable format than a .pdf or .docx, and it is ideal for documentation because its structure is explicit and easily interpretable by automated systems like Crafter.ai.

How to Create a .md File

No special programs are needed to create a .md file. You can use basic text editors included in your operating system.

  • On Windows:
    1. Open Notepad.
    2. Write or paste your text.
    3. Go to File > Save As....
    4. In the "Save as type" box, select "All Files (.)".
    5. In the "File name" field, write the name you prefer followed by .md (e.g., guide_product.md).
    6. Click Save.
  • On macOS:
    1. Open TextEdit.
    2. Write or paste your text.
    3. Go to the Format menu > Make Plain Text.
    4. Go to File > Save....
    5. In the "Save As" field, write the name you prefer followed by .md (e.g., guide_product.md).
    6. Click Save.

Conclusion: Why These Practices Work with Crafter.ai?

Adopting these guidelines leads to three main advantages when using the Crafter.ai platform:

  1. More Accurate Retrieval: Modular documents enriched with metadata allow Crafter.ai's Document Management functionality to more accurately identify the most relevant text "chunks" to the user's query.
  2. More Relevant Generation: By providing the system with clean, well-structured, and unambiguous context, the risk of inaccurate responses is reduced, resulting in more accurate and faithful outcomes.
  3. Platform Efficiency: A clear and well-organized context allows Crafter.ai to process information and generate responses more quickly and consistently.