# Document administration troubleshooting

Use this page to find a document or category, recover an unexpected list state, and maintain
categories or document order in the Documents area.

## Document administration troubleshooting

Document administration is the work of finding and organizing documentation records, then recovering
the list when filters, versions, categories, or access conditions change what you see.
Use the Documents area to manage and organize documentation.
A category is a group of documents in the selected project.
Document order is the arrangement of records in the ordering surface.

| If you need to… | Go to |
|---|---|
| Find a document or category | [Find the document or category involved](#find-the-document-or-category-involved) |
| Recover an empty, filtered, or unavailable list | [Recover from an unexpected list state](#recover-from-an-unexpected-list-state) |
| Create, edit, delete, or reorder categories | [Maintain categories and document order](#maintain-categories-and-document-order) |
| Manage the document record itself | [Administer documents](doc:administer-documents) |
| Edit document content | [Create and edit a document](doc:create-and-edit-a-document) |
| Review document access | [Document access reference](doc:document-access-reference) |
| Match a message to broader help | [General error messages](doc:general-error-messages) |
| Find cross-surface recovery guidance | [Common issues and solutions](doc:common-issues-and-solutions) |

## Before you start

**Prerequisites**

| Have this ready | Why it matters |
|---|---|
| A selected project | Documents and categories load only when a project is available. |
| An authenticated session | Document and category data loads after authentication is available. |
| The document title, category name, or list condition you are investigating | These details help you choose the right search, filter, or recovery path. |

If no project is selected, the category area displays `No project selected` and
`Select a project to view categories`. The Documents area displays `Select a project to view documents`.
If the session is unauthenticated, the category area displays `Authentication required`.

## Find the document or category involved

A document list is the working list of documentation records; use its search, filters, category
selection, sort order, and view choice to narrow the list before changing anything.

**Prerequisites**

- Have a selected project and an authenticated session.

**Steps**

1. Open the Documents area.
2. Enter search text in **Search documents...**.
3. Select **Clear search** when it appears and you want to remove the search text.
4. Choose the list options that match what you need to find.

   | If you need to… | Select or enter |
   |---|---|
   | Include every document type | **All** in the type filters |
   | Find manually maintained documents | **Manual** |
   | Find generated documents | **Generated** |
   | Include every document status | **All** in the status filters |
   | Find draft work | **Draft** |
   | Find published documentation | **Published** |
   | Find archived documentation | **Archived** |
   | Include every category | **All Documents** |
   | Find one category | Enter its name in **Category search** in **Categories** |
   | Switch between available document versions | **Version** |
   | Scan document cards | Card view with the **View toggle** |
   | Read column headers | List view with the **View toggle** |
   | Return to the previous results page | **Previous page** |
   | Open a specific results page | The page number |
   | Move to the next results page | **Next page** |

5. Use the **Sort control** to change the order of the list.
6. In list view, read the headers **Document**, **Type**, **Status**, **Category**, and **Updated**
   to identify the record and its current list information.

**Result:** The list is narrowed to the document or category you need to inspect, and list view
shows the document, type, status, category, and updated columns.

## Recover from an unexpected list state

The list can change because a search, filter, category, project, or version changes the records being
shown. Check the visible condition before treating an empty or changed list as lost documentation.

**Prerequisites**

- Have the affected project or category in mind.

**Steps**

1. Check the active filters and document count above the list.
2. If the list is empty after a search, remove the search text with **Clear search**.
3. If the list is still empty, select **All** in the type filters.
4. Select **All** in the status filters.
5. If the category list is empty, read the message `No categories yet.`.
6. If a category search returns nothing, read the message `No matches.`.
7. If no project is selected, return to the project selector before using the category area.
8. If a non-active version is selected, use the **Version** selector to switch to the active version.
9. If the page is in order-editing mode, select **Exit edit mode** to return to the document list.
10. If **New Document** is not available, continue with the list and category controls that are
   present on the page.

| What you see | What it means | Next action |
|---|---|---|
| `No project selected` | A project is not available to the page. | Return to the project selector before using categories or document data. |
| `No categories yet.` | The selected project has no categories in the category area. | Work from **All Documents** or create a category if **Add Category** is available. |
| `No matches.` | The category search does not match a category. | Clear the category search or use **All Documents**. |
| A `Draft`, `Deprecated`, or `Archived` version notice | The selected version is not active. | Switch to the active version above the notice. |
| **Exit edit mode** | The page is showing the sortable ordering surface. | Return to the normal document list. |

**Result:** You have either restored the intended list context or identified the project, category,
version, or edit-order condition that explains the list.

## Maintain categories and document order

Use the ordering surface to arrange the selected project's records.

**Prerequisites**

- Have a selected project.
- Confirm that the list itself is showing the intended project and category context.

### Create a category

**Steps**

1. Select **Add Category** to open the category form.
2. Enter the category name in **Name \***.
3. Review **Slug \*** after entering the name.
4. Enter an optional value in **Description**.
5. Select an option under **Icon**.
6. Select an option under **Color**.
7. Select **Create** to create the category.

The create form generates **Slug** from **Name** by converting the name to lowercase, replacing
spaces with hyphens, and removing characters other than letters, numbers, and hyphens.

**Result:** The category form closes after the category is created.

### Cancel a category change

**Steps**

1. In the category form, select **Cancel**.

**Result:** The category form closes without saving the change.

### Edit a category

**Steps**

1. Select **Edit category** on the category row.
2. Enter the category name in **Name \***.
3. Review the value in **Slug \***.
4. Enter the category description in **Description**.
5. Select an option under **Icon**.
6. Select an option under **Color**.
7. Select **Save** to save the category changes.

**Result:** The category form closes after the category is updated.

### Reorder categories or documents

**Steps**

1. Select **Edit order**.
2. In the category area, use **Drag to reorder** to move a category.
3. In the ordering surface, drag a document to its required position.
4. Select **Exit edit mode** when the ordering is complete.

**Result:** The page returns to the normal document list with the revised ordering request completed.

### Review category deletion

**Warning:** Deleting a category moves all documents in it to `Uncategorized` and also deletes its
subcategories.

**Steps**

1. Select **Delete category** on the category row.
2. Read the confirmation message: `All documents in this category will be moved to "Uncategorized". Subcategories will also be deleted.`
3. Select **Cancel** to keep the category and its organization.
4. Select **Delete** only when moving the documents and deleting the subcategories is intended.

**Result:** **Cancel** closes the dialog without confirming the deletion; **Delete** confirms the
category deletion.

## When recovery does not work

Use the exact message on screen to choose the next safe diagnostic action. Do not repeat a destructive
operation when the message does not change.

| Message | What it means | Next action |
|---|---|---|
| `Authentication required` | The category area cannot load for the current session. | Use an authenticated session before reopening the Documents area. |
| `Loading...` | The category area is loading. | Wait for the category list to finish loading. |
| `Failed to delete category` | The category deletion request failed. | Keep the category context and use [Common issues and solutions](doc:common-issues-and-solutions) for the next diagnostic path. |
| **Delete Document** | The document delete dialog's confirmation control. | Match a failed request to the document deletion message below. |
| `Failed to delete document:` | The document deletion request failed. Text after the colon gives the returned reason; when no reason is returned, the message ends with `Unknown error`. | Do not repeat the deletion until the returned reason is understood. |
| `Failed to reorder documents. Please try again.` | The document ordering request failed. | Leave the list in its current order and retry only after checking the ordering context. |
| `Failed to reorder categories. Please try again.` | The category ordering request failed. | Leave the category order unchanged and retry only after checking the project context. |
| `Failed to save category` | The category save failed without a more specific message. | Keep the form values and use [General error messages](doc:general-error-messages) for broader diagnosis. |

The **Delete Document** control belongs to the document delete dialog. A failure from that control
uses the document deletion message in the table above.

The category edit and delete controls appear on category-row hover. The category drag handle appears
in edit-order mode. The Documents list shows **New Document** only when that action is available to
the list. These conditions explain why a control can be absent without changing the document list.

**Result:** You have the exact failure message, have avoided repeating a destructive action, and have
the appropriate broader help page for the next diagnostic step.

## What to do next

Use the next page according to the work that remains:

| If the next task is to… | Continue with |
|---|---|
| Manage the full document record | [Administer documents](doc:administer-documents) |
| Edit document content | [Create and edit a document](doc:create-and-edit-a-document) |
| Review document changes | [Document changes](doc:document-changes) |
| Review access controls | [Document access reference](doc:document-access-reference) |
| Diagnose a general application message | [General error messages](doc:general-error-messages) |
| Resolve a cross-surface problem | [Common issues and solutions](doc:common-issues-and-solutions) |