> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lighton.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Best Practices for Organizing and Using Workspaces in Paradigm

> Learn how to structure, manage, and utilize workspaces effectively to enhance collaboration, streamline workflows, and boost productivity across your enterprise.

## Main function: Parsed RAG collections

Paradigm workspaces are designed to **organize and make accessible all types of unstructured documentation** using a **parsed RAG (Retrieval-Augmented Generation) collection** architecture.

<Warning>
  **Important reminder**

  The workspace description in Paradigm is currently **not used** by the RAG system. It serves only as documentation for administrators. The RAG system relies solely on the content of the documents themselves.
</Warning>

### What is a Parsed RAG Collection?

Each workspace contains a collection that :

* **Automatically parses** uploaded documents, whatever their format (PDF, DOCX, XLSX, images, etc.)
* **Extracts and structures** unstructured content to make it comprehensible to AI
* **Generates embeddings** for advanced semantic search
* **Contextualizes** answers based on all workspace documents

<Tip>
  **Key benefit**

  Thanks to RAG parsing, Paradigm can understand and query any technical, commercial, legal or operational documentation, even if it's heterogeneous and unstructured. The system automatically transforms your documents into a searchable knowledge base.
</Tip>

**Note**: The workspace description is currently **not used** by the system and serves only as documentation for administrators.

### Supported documentation types

RAG collections can parse and include:

* **Technical documentation**: specifications, API docs, architecture, code
* **Business documents**: procedures, guides, training, playbooks
* **Legal resources**: Contracts, NDAs, policies, compliance
* **Customer data**: Specifications, deliverables, communications
* **Miscellaneous knowledge**: Wikis, notes, presentations, spreadsheets

***

## Organization Strategies

### Recommended Approach: Organization by Knowledge Area

Since workspaces function as RAG collections, organize them by **coherent knowledge domain** rather than by organizational structure:

```jsx theme={null}
Exemples of optimal workspace organization :

✅ By technical field :
  • "Engineering - Platform Architecture"
  • "Engineering - API Documentation" 
  • "Engineering - DevOps & Infrastructure"

✅ By business area :
  • "Product - User Research & Insights"
  • "Product - Product Specifications"
  • "Sales - Sales Playbooks & Methodologies"

✅ By regulatory area :
  • "Compliance - GDPR Documentation"
  • "Compliance - SOC2 Evidence"
  • "Legal - Contracts & Agreements"

❌ Avoid (too generic) :
  • "Documents"
  • "Fichiers 2025"
  • "Misc"
```

### Principle of Thematic Coherence

**Why it's important**: RAG works best when documents in the same workspace are thematically related. This enables :

1. **Better contextualization**: AI better understands relationships between similar documents
2. **More precise responses**: Semantic search is more effective in a coherent corpus
3. **Less noise**: Avoids irrelevant results from different domains

**Rule of thumb**: if you're asking "Will these documents be queried together in the same context?", they must be in the same workspace.

### Examples by Organization Type

### ▶**1. Organization by Project (with thematic consistency)**

```jsx theme={null}
Engineering Team
  ├─ Project Phoenix - Technical Docs
  │  └─ Architecture, specs, API docs, test plans
  ├─ Project Phoenix - User Documentation  
  │  └─ User guides, tutorials, FAQs
  └─ Infrastructure - Runbooks
     └─ Procedures, configurations, monitoring
```

**When to use**: Large projects with voluminous documentation and different types of audience

### ▶2. Organization by Functional Area

```jsx theme={null}
Product Organization
  ├─ Product Requirements
  │  └─ PRDs, specs, roadmaps
  ├─ User Research
  │  └─ Interviews, personas, insights
  ├─ Design System
  │  └─ Components, guidelines, patterns
  └─ Analytics & Metrics
     └─ Dashboards, reports, KPIs
```

**When to use**: Teams with distinct areas of expertise and specialized documentation

### ▶3. Hybrid Organization (Recommended)

```jsx theme={null}
Company Knowledge Base
  ├─ Technical - Backend APIs (domaine)
  ├─ Technical - Frontend Components (domaine)
  ├─ Project Phoenix - All Docs (projet)
  ├─ Customer Success - Playbooks (domaine)
  ├─ Sales - Methodologies (domaine)
  └─ Compliance - All Documentation (domaine)
```

**Advantages**: Combines project flexibility with thematic domain consistency

***

## Good Naming Practices

### Recommended format

```jsx theme={null}
[Domain] - [Subdomain or Content Type]
```

### Examples

```jsx theme={null}
✅ Excellent naming (descriptive and thematic) :
  • "Engineering - Platform API Documentation"
  • "Product - Feature Specifications"
  • "Sales - Enterprise Playbooks"
  • "Compliance - Security Policies"
  • "Customer Success - Implementation Guides"

✅ Good naming (clear and consistent) :
  • "Technical Documentation - Backend"
  • "User Research 2025"
  • "Legal - Vendor Contracts"

❌ À éviter (trop vagues pour une recherche efficace) :
  • "Documents"
  • "Workspace 1"
  • "Misc Files"
  • "Archive"
  • "tmp"
```

***

## Size and Number of Workspaces

### Recommendations

| Size Organization         | Number of Workspaces | Principle                 |
| ------------------------- | -------------------- | ------------------------- |
| Small team (\< 10)        | 3-5 workspaces       | Per large area            |
| Medium team (10-50)       | 5-15 workspaces      | Per area and sub-area     |
| Large organization (> 50) | 10-30 workspaces     | By area, team and project |

### When to create a new workspace

```jsx theme={null}
✅ Create a workspace when:
• The topic area is distinct
• The documents will not be searched together
• The members/permissions are different
• The content requires isolation (confidentiality)

❌ Do not create a workspace if:
• It is just to "organize" similar documents
• The same people access it
• The documents are thematically related
• A simple tag/folder would suffice
```

***

## Practical Use Cases

### 1. Consistent Multi-Project Documentation

**Scenario**: Several projects sharing the same technical stack

**Solution**:

```jsx theme={null}
Engineering
  └─ Backend API Documentation (single workspace)
     ├─ Common patterns (files)
     ├─ Project A APIs (files)
     ├─ Project B APIs (files)
     └─ Project C APIs (files)
```

**RAG advantage**: The system can respond to common patterns by drawing on all projects.

### 2. Customer Knowledge Base

**Scenario**: Agency managing several customers

**Solution**:

```jsx theme={null}
Client Services
  ├─ Client A - All Documentation
  │  └─ Contracts, deliverables, communications
  ├─ Client B - All Documentation
  │  └─ Contracts, deliverables, communications
  └─ Internal - Service Methodologies
     └─ Processes, templates, best practices
```

**RAG advantage**: Perfect isolation by customer + reusable methodologies

### 3. Compliance Documentation

**Scenario**: Multiple regulatory requirements

**Solution**:

```jsx theme={null}
Compliance
  ├─ GDPR - Complete Documentation
  │  └─ Policies, audits, DPIAs, procedures
  ├─ SOC2 - Evidence & Controls
  │  └─ Controls, tests, reports, evidence
  └─ ISO 27001 - Documentation
     └─ Policies, procedures, audits
```

**RAG Advantage**: Precise search by regulatory framework

### 4. Onboarding and Training

**Scenario**: Training documentation by role

**Solution**:

```jsx theme={null}
HR - Learning & Development
  ├─ Engineering Onboarding
  │  └─ Setup guides, tech stack, processes
  ├─ Sales Onboarding  
  │  └─ Product training, methodologies, tools
  └─ General Company Onboarding
     └─ Culture, policies, benefits, tools
```

**RAG Advantage**: Customized responses by user role

***

## Workspace Lifecycle

### Creation

1. **Define a** clear and coherent **knowledge domain**
2. **Identify members** working in this area
3. **Create with a descriptive name** for the thematic content
4. **Document purpose** (even if not used by the system, useful for admins)
5. **Start uploading** or **Sync with Datasource** thematically-related documents

### Maintenance

1. **Review members**: Quarterly for standard workspaces
2. **Monitor consistency**: Ensure that new documents remain thematically linked
3. **Clean up regularly**: Remove obsolete documents to improve RAG quality
4. **Check usage**: Identify under-used workspaces

### Offboarding

1. Inactivate user
2. Remove the user's membership from all their custom workspaces
3. Transfer ownership of workspaces if necessary

***

## Audit and Traceability

### **Workspace events** :

* Creation
* Modification (name, description)
* Add/remove members
* Delete

### **Documents events** :

* Upload
* Consult through tools (docsearh, etc.)
* Delete

### **Access events**:

* Access attempts denied
* Permission changes
* Data export