Documentation & Directories

Overview

The Documentation section provides a file-system-like hierarchical structure for browsing and organizing assets in Workunit. Think of directories as folders that group related assets—products, systems, people, and knowledge—into a navigable tree structure.

This guide teaches you how to use the Documentation section, create and manage directories, and build an organized asset library that's easy to navigate for both humans and AI assistants.

What Are Directories?

Directories are containers that organize assets into a tree structure, similar to folders on your computer. They help you group related assets, create logical hierarchies, and make information easier to find.

Directory Hierarchy

Directories can be nested to create multi-level hierarchies. Each directory can contain both assets and subdirectories, allowing you to build complex organizational structures.

Example Directory Structure

Documentation

API Documentation

REST API

Authentication Endpoints

User Management API

GraphQL API

Schema Reference

Query Examples

Example: An "API Documentation" parent directory contains subdirectories for "REST API" and "GraphQL API," each with their own documentation assets. This creates a clear hierarchy that mirrors your technical architecture.

Supported Asset Types

All asset types can be organized in directories. This flexibility lets you create structures that match how your organization thinks about its resources.

Assets You Can Organize in Directories:

✓ Knowledge: Documentation, training materials, standards, research, templates, playbooks

✓ Products: Software products, services, hardware, subscriptions

✓ Systems: Infrastructure, processes, manufacturing systems, logistics

✓ People: Individuals, teams, departments, contractors

Example: Team Documentation Structure

Create a "Engineering Team" directory containing team member profiles (People assets), the services they own (System assets), and their documentation (Knowledge assets)—all in one logical location.

Creating Directories

Creating directories is straightforward. Start with broad categories, then add subdirectories as your documentation library grows.

Creating Your First Directory

When creating a directory, provide a clear name and optional description. Think about the category of documentation this directory will contain.

Good Directory Definition

Name:

API Documentation

Description:

Comprehensive documentation for all API endpoints, including REST and GraphQL interfaces. Contains authentication guides, endpoint references, and integration examples.

Why it's good: Clear, descriptive name that immediately conveys purpose. Detailed description explains what documentation lives here.

Weak Directory Definition

Name:

Docs

Description:

Documentation stuff

Why it's weak: Vague name doesn't specify what kind of documentation. Generic description provides no context about contents.

Nested Directories

Create subdirectories to organize documentation within broader categories. You can nest directories multiple levels deep to match your organizational needs.

Creating Subdirectories

When creating a new directory, you can specify a parent directory to create it as a subdirectory. This builds your hierarchical structure.

Parent: "Engineering" → New Directory: "Backend Services"
Result: Engineering / Backend Services

Moving Directories

You can reorganize by moving directories to different parents or to the root level.

Move "REST API" from root to "API Documentation"
Before: REST API
After: API Documentation / REST API

Pro Tip: Start Broad, Refine Later

Begin with a few top-level directories for major categories. As your documentation grows, add subdirectories to organize further. It's easier to start simple and add structure than to over-organize from the beginning.

Organizing Assets in Directories

Once you've created directories, you can organize assets by placing them in the appropriate directory. This creates a structured library that's easy to navigate.

Moving Assets to Directories

Assets can be moved into directories at any time. When creating a new asset, you can immediately place it in a directory, or you can move existing assets into directories as you organize.

Assigning During Creation

When creating a new asset, specify the directory it should belong to. This keeps your assets organized from the start.

Creating: "REST Authentication Guide"
Directory: API Documentation / REST API
Result: Asset created in correct location

Moving Existing Assets

Edit an asset to change its directory assignment. You can move assets between directories or back to the root level.

Asset: "GraphQL Schema Guide"
Current: (root level)
Move to: API Documentation / GraphQL API

AI-Powered Organization

AI assistants can update assets via MCP to move them into appropriate directories based on content and context.

"Move the deployment runbook to the Operations / Deployment directory"

Root-Level Assets

Not all assets need to be in a directory. Assets at the root level (not assigned to any directory) are accessible and searchable, appearing in the main documentation view.

Good Uses for Root-Level Assets:

• Welcome documents: High-level overview or getting started guides

• Cross-cutting documentation: Resources that don't fit cleanly into one category

• Temporary documents: Work-in-progress documentation before categorization

• Frequently accessed guides: Documents you want readily visible

Browsing the Documentation Section

The Documentation section provides an intuitive interface for navigating your directory structure and finding assets quickly.

Tree Sidebar Navigation

The left sidebar displays your directory structure as an expandable tree. Click to expand directories and view their contents, making it easy to explore your documentation hierarchy.

Directory Icons

Folders indicate directories. Click to expand and view subdirectories and assets within.

Asset Icons

Document icons represent assets. Click to view the asset details and content.

Expand/Collapse

Chevron icons show expandable directories. Click to toggle between expanded and collapsed states.

Viewing Directory Contents

When you click on a directory in the tree, the main content area displays all assets and subdirectories within that directory. This provides a clear view of what documentation is organized where.

• Breadcrumb navigation: Shows your current location in the directory hierarchy

• Subdirectories listed first: Easy access to navigate deeper

• Assets displayed with metadata: Name, type, description visible at a glance

• Quick actions: View, edit, or move assets directly from the listing

AI Integration with Directories

AI assistants can navigate, create, and manage directories via MCP, making it easy to organize assets through natural language commands.

Example Prompts

You can ask AI assistants to manage directories using natural language:

"Create a new folder called Backend Services inside the Engineering directory"

"Move all the API documentation assets into the API Docs folder"

"Show me what's in the Onboarding directory"

"Find all assets about authentication in the API Documentation folder"

"Reorganize the documentation structure: move REST API and GraphQL into a new API Reference parent folder"

"Delete the empty Old Docs directory"

MCP Directory Operations

For developers building integrations, here's the technical reference. The MCP directory tool uses a polyaction pattern with these operations:

create

directory(action: "create", name: "API Documentation", parent_id: null)

Creates a new directory. Optionally specify a parent_id to create a subdirectory.

get

directory(action: "get", directory_id: "dir-uuid")

Retrieves directory details including name, description, parent, and contained assets.

list

directory(action: "list", parent_id: null)

Lists directories. Use parent_id to list subdirectories, or null for root-level directories.

update

directory(action: "update", directory_id: "dir-uuid", name: "New Name")

Updates directory properties like name or description.

delete

directory(action: "delete", directory_id: "dir-uuid")

Deletes an empty directory. Assets must be moved before deletion.

move

directory(action: "move", directory_id: "dir-uuid", new_parent_id: "parent-uuid")

Moves a directory to a new parent. Use null for new_parent_id to move to root.

Searching Within Directories

The search tool supports directory filtering, allowing AI assistants to find assets within specific directories or at the root level only.

Search Within Directory

search(query: "authentication", directory_id: "api-docs-uuid")

Searches only within the specified directory and its subdirectories. Perfect for scoped documentation searches.

Search Root Level Only

search(query: "getting started", root_only: true)

Searches only assets at the root level (not in any directory). Useful for finding uncategorized assets.

Search Everything

search(query: "deployment guide")

Without directory_id or root_only, searches across all assets regardless of directory.

Best Practices

Apply these principles to create an organized, intuitive documentation structure:

Logical Organization

Mirror Your Architecture

Organize documentation to reflect your technical architecture. If you have frontend and backend systems, create directories that mirror that structure.

Group by Purpose

Create directories based on how documentation is used. API docs together, training materials together, operational runbooks together.

Limit Nesting Depth

Avoid going more than 3-4 levels deep. Overly nested structures are harder to navigate than flat, well-named directories.

Keep Related Content Together

If assets reference each other frequently, place them in the same directory or nearby in the hierarchy.

Naming Conventions

Be Specific and Descriptive

"API Documentation" is better than "Docs." "Backend Services" is better than "Services."

Use Consistent Terminology

If you call something "API" in one place, don't call it "Web Service" elsewhere. Consistency helps findability.

Avoid Abbreviations

Unless they're universally understood in your organization, spell things out. "Authentication" not "Auth."

Use Title Case

Directory names should be properly capitalized for readability: "User Management" not "user management."

When to Use Directories

You Have 10+ Assets

Small asset collections don't need directories. Once you reach double digits, organization becomes valuable.

Clear Categories Emerge

If you naturally think "this is API documentation" versus "this is training," directories will help maintain that organization.

Multiple Team Areas

When different teams own different documentation areas, directories provide clear ownership boundaries.

Documentation Hierarchy Exists

If you have overview docs, detailed guides, and reference materials, directories help express that hierarchy.

Next Steps

Ready to organize your assets with directories? Here's where to go next:

View Documentation

Browse your existing assets and directory structure

Create Asset

Add new assets and organize them in directories

Managing Assets

Learn about asset types and their organization

MCP Integration

Connect AI assistants to manage directories via Model Context Protocol

Questions About Documentation?

We're here to help you organize your assets effectively with directories.

Documentation Community Discussions