# Administer documents

Document administration is the work of maintaining document records, their categories, their list
order, and the way you reach each record in a project. A document record is an item in the project's
documentation list, and a category groups records so your team can find them. Use administration
when you need to organize existing documentation or maintain those categories.

The Documents workspace is the project area where these records are listed and organized.

| If you need to… | Go to |
|---|---|
| Find an existing document record | [Find a document record](#find-a-document-record) |
| Understand the list, categories, views, and dialogs | [Understand the Documents screen](#understand-the-documents-screen) |
| Filter, reorder, or change categories | [Organize document records and categories](#organize-document-records-and-categories) |
| Create or edit document content | [Create and edit a document](doc:create-and-edit-a-document) |
| Review document states and actions | [Document changes](doc:document-changes) |
| Manage document access | [Document access reference](doc:document-access-reference) |
| Recover from an administrative problem | [Document administration troubleshooting](doc:document-administration-troubleshooting) |

## Before you start

Before you administer documents, select the project you want to manage and sign in. Document
loading requires both a project and a signed-in session. The category area appears only after
a project is selected. Have the saved document or category you need to manage in mind before you
begin.

| Have this ready | Why it matters |
|---|---|
| The project that contains the documents | The Documents list and category area use the selected project. |
| A saved document record or category to manage | The available list, category, and record actions depend on the returned project data. |
| A signed-in session | Document and category loading waits for an authenticated session. |

The current project, version, category, document values, and permissions depend on the account and
project you are using. With the project selected and the record or category in mind, continue to
[Find a document record](#find-a-document-record).

## Find a document record

Find an existing document record when you need to open it rather than create or edit its content.

**Prerequisites**

- You have selected a project.
- You know enough of the document title or category to narrow the list.

**Steps**

1. Open the Documents destination for the selected project.
2. To search by text, enter a value in **Search documents**.
3. To narrow the document type, select one of **All**, **Manual**, or **Generated**.
4. To narrow the document status, select one of **All**, **Draft**, **Published**, or **Archived**.
5. To narrow the category, select **All Documents** or a category in the category area.
6. Select the document record you need from the filtered list.

**Result:** The selected document record is open for the next document task.

## Understand the Documents screen

The Documents screen combines a document list with category navigation. The list can use cards or
rows, and category administration opens in dialogs.

The main areas are:

| Area | What it contains |
|---|---|
| Document list | Search, type and status filters, sorting, view selection, document cards or rows, and pagination. |
| Category area | **Categories**, category search, **All Documents**, project categories, and **Add Category**. |
| Version selector | **Version**, when the selected project has one or more versions. |
| Order controls | **Edit order** and drag-and-drop ordering when a project is selected. |
| Category dialogs | **Create Category**, **Edit Category**, and **Delete Category** dialogs. |

In list view, the row headers are Document, **Type**, **Status**, **Category**, and **Updated**.
In card view, documents appear as cards instead of rows.

When you create or edit a category, the dialog contains **Name**, **Slug**, **Description**,
**Icon**, and **Color**. **Name** and **Slug** are required. **Description** is optional. In create
mode, entering a name generates a lowercase slug with spaces replaced by hyphens and other
characters removed.

## Organize document records and categories

Organizing documents means narrowing the list, choosing how it is displayed, changing its order,
and maintaining categories.

### Filter and change the list

**Prerequisites**

- You have selected a project.
- The Documents list is open.

**Steps**

1. Enter text in **Search documents** when you need a text match.
2. When search text is present, select **Clear search** to remove it.
3. Select a document type from **All**, **Manual**, or **Generated**.
4. Select a document status from **All**, **Draft**, **Published**, or **Archived**.
5. When the version selector is available, select a value in **Version**.
6. In the Documents list, select the sorting control beside the view-selection control.
7. Select a display mode in the view toggle.
8. Select **Clear** in the category filter indicator to remove the selected category.
9. Use **Previous page**, a page number, or **Next page** to move through the list.

**Result:** The Documents list shows the records using the selected filters, sort, view, and
category selection.

### Reorder documents or categories

**Prerequisites**

- You have selected a project.
- The documents or categories you want to reorder are visible.

**Steps**

1. Select **Edit order**.
2. Use drag and drop to reorder documents within a category, or to reorder categories and documents
   when no category is selected.
3. Select **Exit edit mode** when the order is correct.

**Result:** The Documents screen returns to its normal list view with edit-order mode closed.

### Create or edit a category

**Prerequisites**

- You have selected a project.
- The category area is visible.

**Steps**

1. Select **Add Category** to open **Create Category**.
2. Enter the category name in **Name**.
3. Review the generated value in **Slug**.
4. Enter a value in **Description**, if needed.
5. Select an option in **Icon**.
6. Select an option in **Color**.
7. Choose the category action in this table:

   | Goal | Action |
   |---|---|
   | Create a category | Select **Create**. |
   | Edit a category | Select its **Edit category** control, update the fields, and select **Save**. |

8. Select **Cancel** to close either dialog without saving.

**Result:** The category dialog closes after the create or edit action, and the category area can be
refreshed with the updated category.

### Delete a category or document

**Prerequisites**

- You have selected the category or document to remove.
- You have checked that the removal is intended.

**Steps**

1. Choose the removal path in this table:

   | Goal | Action |
   |---|---|
   | Delete a category | Select the category's **Delete category** control. |
   | Delete a document | Select the document's **Delete Document** control. |

2. Read the confirmation in the path you selected:

   | Goal | Action |
   |---|---|
   | Delete a category | Read `All documents in this category will be moved to "Uncategorized". Subcategories will also be deleted.` |
   | Delete a document | Read the document confirmation dialog. |

3. Choose the confirmation action in this table:

   | Goal | Action |
   |---|---|
   | Keep the category | Select **Cancel**. |
   | Confirm the category deletion | Select **Delete**. |
   | Confirm the document deletion | Follow the document confirmation dialog and select its **Delete Document** control. |

**Result:** The selected delete operation is either cancelled or confirmed from its dialog.

## Handle different document-list states

The Documents screen changes its available areas according to the selected project, category,
version, filters, and edit-order mode.

| If you need to… | Use this path |
|---|---|
| View documents for a project | Select a project first; the category area then becomes available. |
| View all project documents | Select **All Documents**. |
| Work within one category | Select that category; the list receives the category filter. |
| Work with a non-active version | Read the version notice, then switch to the active version in **Version**. |
| See why no records are listed | Check whether a search, type, or status filter is active; the empty state changes when a search is present. |
| Change ordering | Select **Edit order**; the list changes to the sortable ordering surface. |

**Prerequisites**

- You are on the Documents screen.

**Steps**

1. Select the path that matches your goal in the table above.

**Result:** The Documents screen shows the list or ordering state that matches your selection.

If no project is selected, the category area displays `No project selected` and
`Select a project to view categories`. The page also prompts with
“Select a project to view documents”.

## When document administration goes wrong

Use the exact message on screen to choose the applicable response. Do not repeat a destructive
action when the message identifies a failed request.

| What you see | Meaning and next action |
|---|---|
| `Loading...` | The category area is loading. Wait for the category list to appear. |
| `Loading document…` | The document record is loading. Wait for the record result. |
| `Document failed to load.` | The record did not load. Use [Document administration troubleshooting](doc:document-administration-troubleshooting). |
| `No categories yet.` | The project has no categories in the category area. Use **Add Category** if you need one. |
| `No matches.` | The category search has no matching category. Change the category search value. |
| `Failed to save category` | The category save request failed. Review the category values and try the save again. |
| `Failed to delete category` | The category deletion request failed. Check that the category remains selected before trying again. |
| `Failed to delete document:` | The document deletion request failed. Check that the record remains in the list before trying again. |
| `Failed to reorder documents. Please try again.` | The document reorder request failed. Check the displayed order before trying again. |
| `Failed to reorder categories. Please try again.` | The category reorder request failed. Check the displayed category order before trying again. |
| `All documents in this category will be moved to "Uncategorized". Subcategories will also be deleted.` | This is the category deletion warning. Select **Cancel** to keep the category, or **Delete** to confirm the operation. |

The `Unauthorized` reload handling belongs to the document detail loading flow. Viewer-rendered
chapter, command-palette, viewport, annotation, and screenshot messages belong to the document
viewer rather than document administration.

## What to do next

After you finish an administrative change, continue with the task that matches what you need to
do next:

| Next need | Page |
|---|---|
| Create a document or edit its content | [Create and edit a document](doc:create-and-edit-a-document) |
| Review document states and actions | [Document changes](doc:document-changes) |
| Manage document access | [Document access reference](doc:document-access-reference) |
| Resolve an administrative issue | [Document administration troubleshooting](doc:document-administration-troubleshooting) |

The document record remains the hand-off point for content work and document-specific actions.