Creating documentation

Learn how to add documentation to Tessl packages to provide usage information and examples to AI agents.

Documentation in tiles helps AI agents understand how to use your libraries, APIs, and internal systems. This guide shows you how to manually create and add documentation to tiles using the Tessl CLI.

Choosing between manual and automated creation

Manual creation gives you full control over content and works for any system or API. If you have source code access (JavaScript, TypeScript, or Python) and want evaluation data, see Autogenerating documentation for the automated approach.

Prerequisites

Before you begin, make sure you have:

• Tessl CLI installed (see Installation)

• Authenticated with Tessl (tessl login)

• A workspace created (see Workspace management)

Creating a tile with documentation

Step 1: Create a new tile

Use the tessl tile new command to create a new tile structure:

tessl tile new --name myworkspace/util-formatter --path ./my-tile

This creates a tile directory with a tile.json manifest file.

Step 2: Add your documentation

Create a markdown file with your documentation:

# Create docs directory
mkdir -p ./my-tile/docs

# Create your documentation file
cat > ./my-tile/docs/index.md << 'EOF'
# Formatter Util

A colorful logging formatter for pretty terminal output.

## Package Information

- **Package Name**: util-formatter
- **Language**: Python
- **Installation**: `pip install git+https://github.com/<username>/<repo>.git`
- **Requirements**: Python 3.8+

## Core Imports

    from util_log_formatter import format_log
    from util_log_formatter.formatter import ColorLogFormatter

## Usage

### Use as a print formatter

    from util_log_formatter import format_log

    print(format_log("info", "Server started"))
    print(format_log("warning", "High memory usage"))
    print(format_log("error", "Something went wrong"))

### Use as a logging formatter

    import logging
    from util_log_formatter.formatter import ColorLogFormatter

    logger = logging.getLogger("myapp")
    handler = logging.StreamHandler()
    handler.setFormatter(ColorLogFormatter())
    logger.addHandler(handler)
    logger.setLevel(logging.INFO)

    logger.info("Application started")
EOF

Step 3: Update the tile manifest

Edit tile.json to reference your documentation:

{
  "name": "myworkspace/util-formatter",
  "version": "1.0.0",
  "summary": "A colorful logging formatter for pretty terminal output",
  "docs": "docs/index.md",
  "describes": "pkg:npm/my-company/[email protected]",
  "private": true
}

Key fields:

• name: Your workspace and tile name in workspace/tile-name format

• version: Semantic version (semver)

• docs: Path to your documentation file (relative to tile.json)

• describes: (Optional) Package URL (PURL) if documenting a specific package

• private: Set to true for workspace-only access

Step 4: Add a Registry README (optional)

Create README.md in your tile directory to customize how it appears in the Tessl Registry:

# util-formatter

This tile describes our internal util-formatter library, used as a colorful logging formatter for pretty terminal output.

## Internal guidance

All internal applications for MyCompany should use this terminal helper to help with look and feel.
Contact unified-services group to update this or fix bugs.

Note: The README is shown in the Registry interface but not passed to agents.

Step 5: Validate your tile

Before publishing, validate your tile structure:

tessl tile lint ./my-tile

This checks:

• tile.json format and structure

• Required fields

• Documentation file paths exist

• Markdown validity

Step 6: Publish your tile

Publish your tile to the Tessl Registry:

tessl tile publish ./my-tile --workspace myworkspace

By default, tiles are published as private and only accessible to workspace members.

Documentation structure

You can organize documentation in multiple files:

my-tile/
├── tile.json
└── docs/
    ├── index.md           # Main documentation
    ├── getting-started.md # Getting started guide
    ├── api-reference.md   # API reference
    └── examples.md        # Usage examples

The docs field in tile.json points to the main entry point (usually index.md).

Writing effective documentation

What to include

• Package information - Name, language, installation instructions

• Core imports - Key modules and classes to import

• Usage examples - Common use cases with code examples

• API reference - Key functions, methods, parameters

• Best practices - Patterns and conventions specific to your code

What to avoid

• Implementation details - Focus on usage, not internals

• Outdated examples - Keep examples current with your code

• Overly verbose explanations - Be concise and actionable

Example documentation template

# Library Name

Brief description of what this library does.

## Package Information

- **Package Name**: your-package
- **Language**: Python/JavaScript/etc
- **Installation**: installation command
- **Requirements**: version requirements

## Core Imports

    import statements or require statements

## Usage

### Common Use Case 1

Brief description

    code example

### Common Use Case 2

Brief description

    code example

## API Reference

### FunctionName

Description of what it does

**Parameters:**
- `param1` (type): description
- `param2` (type): description

**Returns:** description

**Example:**

    usage example

Updating documentation

To update documentation in a published tile:

1. Edit your documentation files

2. Update the version number in tile.json (following semantic versioning)

3. Validate with tessl tile lint

4. Publish the new version with tessl tile publish

# Edit your docs
vim my-tile/docs/index.md

# Update version in tile.json (e.g., from "1.0.0" to "1.1.0")
vim my-tile/tile.json

# Validate the changes
tessl tile lint ./my-tile

# Publish the updated version
tessl tile publish ./my-tile --workspace myworkspace

Users can update to the new version by running:

tessl install myworkspace/util-formatter

Sharing your tile

To allow team members to access your tile, add them to your workspace:

tessl workspace add-member --user <tessl-user-id> --role member --workspace myworkspace

The member role gives read-only access to tiles. See Roles for more information.

How documentation is used by agents

When a tile is installed in a project, the documentation becomes available to AI agents through Tessl's MCP (Model Context Protocol) integration. Agents can:

• Query documentation on-demand when needed

• Search across all installed tile documentation

• Reference specific sections when generating code

• Follow patterns and examples from your docs

Documentation is loaded on-demand rather than always present in context, making it efficient for agents to work with many tiles.

Best practices

• Use the docs field - Documentation must be referenced in the docs field of tile.json

• Write clear descriptions - The summary in your tile.json helps agents discover your tile

• Include code examples - Show real usage patterns with working code

• Keep it current - Update documentation when your code changes

• Version semantically - Use semantic versioning when publishing updates

• Test before publishing - Use tessl tile lint to validate structure

Combining approaches

For packages with source code, you can start with automated generation to get baseline documentation, then manually refine it for precision. Add manual tiles for internal services and APIs without source code access. This gives you the speed of automation with control where it matters.

Related documentation

• Autogenerating documentation - Automated tile creation

• Distributing via registry - Share and maintain tiles via the registry

• Configuration files - Complete reference for tile.json structure

• CLI commands - Full command reference

• Workspaces - Understanding workspaces