# Creating documentation

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.

{% hint style="info" %}
**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](broken://pages/igFZovBVTWCexNCUgNsz) for the automated approach.
{% endhint %}

## Prerequisites

Before you begin, make sure you have:

* Tessl CLI installed (see [Installation](/introduction-to-tessl/installation.md))
* Authenticated with Tessl (`tessl login`)
* A workspace created (see [Workspace management](/reference/cli-commands.md#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:

```bash
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:

```bash
# 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:

```json
{
  "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/util-formatter@1.0.0",
  "private": true
}
```

**Key fields:**

* **name**: Your workspace and tile name in `workspace/tile-name` format
* **version**: Semantic version ([semver](https://semver.org/))
* **docs**: Path to your documentation file (relative to tile.json)
* **describes**: (Optional) Package URL ([PURL](https://github.com/package-url/purl-spec)) 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:

```markdown
# 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:

```bash
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:

```bash
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

```markdown
# 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](https://semver.org/))
3. Validate with `tessl tile lint`
4. Publish the new version with `tessl tile publish`

```bash
# 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:

```bash
tessl install myworkspace/util-formatter
```

## Sharing your tile

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

```bash
tessl workspace add-member --username <tessl-username> --role member --workspace myworkspace
```

The `member` role gives read-only access to tiles. See [Roles](/reference/roles.md) 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

{% hint style="info" %}
**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.
{% endhint %}

## Related documentation

* [Autogenerating documentation](broken://pages/igFZovBVTWCexNCUgNsz) - Automated tile creation
* [Distributing via registry](/distribute/distributing-via-registry.md) - Share and maintain tiles via the registry
* [Configuration files](/reference/configuration.md) - Complete reference for `tile.json` structure
* [CLI commands](/reference/cli-commands.md) - Full command reference
* [Workspaces](/reference/workspaces.md) - Understanding workspaces


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.tessl.io/create/creating-documentation.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.