# Documents overview

## Documents overview

A document is a principal record that you create and edit inside a project. The
**Documents** destination is the project workspace where you organize those records,
narrow the list, and open a saved document for the next task.

| If you need to… | Go to |
|---|---|
| Check the project and list conditions before working | [Before you start](#before-you-start) |
| Locate a saved document by category, text, type, status, or order | [Find documents](#find-documents) |
| Understand the cards, list headings, views, and pages | [Understand the document list](#understand-the-document-list) |
| Open a document from the list | [Open a saved document](#open-a-saved-document) |
| Create or edit a document | [Create and edit a document](doc:create-and-edit-a-document) |
| Compare revisions | [Compare document revisions](doc:compare-document-revisions) |
| Translate a document | [Translate a document](doc:translate-a-document) |
| Review document states and actions | [Document changes](doc:document-changes) |
| Read published documentation | [Published documentation](doc:published-documentation) |

## Before you start

**Prerequisites**

- Select a project before working with its categories and documents.

The Documents list and category sidebar depend on the selected project. Without one,
the page shows **No project selected** and **Select a project to view categories**.
With a project selected, the category sidebar loads the categories for that project.

If the project has versions, the page also provides **Version**. Its selected option
comes from the current version context.

With a project selected, continue to [Find documents](#find-documents).

## Find documents

A category is a group used to organize related documents. Use the category sidebar and
the document-list controls to narrow the list until the document you need is visible.

**Prerequisites**

- Have a project selected.
- Know enough about the document to choose a category, search text, type, status, or
  sort order.

**Steps**

1. In the category sidebar, select **All Documents** to search across the project, or
   select a category to limit the list.
2. If you selected a category, select **Clear** in the category filter indicator to
   remove that category filter.
3. In **Search documents...**, enter text from the document you need.
4. Select one type filter: **All**, **Manual**, or **Generated**.
5. Select one status filter: **All**, **Draft**, **Published**, or **Archived**.
6. Open the sort menu and select the option that matches the way you want to locate the
   document.

   | If you need to… | Select |
   |---|---|
   | Keep the project's defined order | **Custom Order** |
   | Start with the most recently changed documents | **Recently Updated** |
   | Start with the least recently changed documents | **Least Recently Updated** |
   | Start with the newest documents | **Newest First** |
   | Start with the oldest documents | **Oldest First** |
   | Scan titles from A to Z | **Title (A-Z)** |
   | Scan titles from Z to A | **Title (Z-A)** |

**Result:** The list shows the documents matching the category, search text, type, and
status choices, in the selected order.

Continue with the document-list presentation before opening a result.

## Understand the document list

The document list is the working surface for choosing a saved record. It can show cards
or a list. The first list heading identifies the document, followed by **Type**,
**Status**, **Category**, and **Updated**.

The page also provides **Card view** and **List view**, plus **Previous page** and
**Next page** when the document list spans more than one page. **Edit order** changes
the surface to an ordering mode for categories and documents; select it only when you
need to change their order.

The fields **Version**, **Search documents...**, and **Search...** have no required
marker. **Search...** belongs to the category sidebar and is shown
when a project is selected and the category sidebar has loaded.

| What you see | What it means |
|---|---|
| **Search...** in the category sidebar | Narrow the category list. |
| **Search documents...** above the document results | Narrow the document results by search text. |
| Cards | Each document is presented as a selectable card. |
| The first heading identifies the document; the following headings are **Type**, **Status**, **Category**, and **Updated** | Each visible row is organized by those document details. |
| **Edit order** mode | Categories and documents are presented for reordering. |
| An empty result | The empty-state behaviour depends on whether a search is active. |

When the document you need is visible, continue with [Open a saved document](#open-a-saved-document).

## Open a saved document

Opening a saved document takes you from the organized list to that document's record
view. Use this procedure when the document already exists.

**Prerequisites**

- Have a project selected.
- Locate the document card or list entry.

**Steps**

1. Select the document card or list entry.

**Result:** The document opens in its detail page. If the list shows an empty or error
branch instead, continue with [Handle list branches](#handle-list-branches).

If you need a new record instead, select **New Document** in the document list. The
creation and editing procedure is described in [Create and edit a document](doc:create-and-edit-a-document).

## Handle list branches

The list changes according to the project, category, search, and document results you
have. Follow the alternative that matches what is on screen.

### Select a project

**Prerequisites**

- The Documents destination is open.

**Steps**

1. If the page shows **No project selected** or **Select a project to view categories**,
   select a project before using the category sidebar or document list.

**Result:** The category sidebar and document list can load for the selected project.

### Create the first category

**Prerequisites**

- A project is selected.
- The category sidebar shows `No categories yet.`.

**Steps**

1. Select **Add Category**.

**Result:** The category-creation path opens.

### Recover from an empty category search

**Prerequisites**

- A project is selected.
- The category sidebar shows `No matches.`.

**Steps**

1. Change the text in **Search...** or clear the category search.

**Result:** The category list shows the categories matching the revised search.

### Recover from an empty document result

**Prerequisites**

- The document list shows no result after a search.

**Steps**

1. Change the text in **Search documents...** or remove the active filters.

**Result:** The document list shows the results matching the revised search and filters.

### Leave edit-order mode

**Prerequisites**

- Edit-order mode is active.

**Steps**

1. Use the ordering surface for category or document order.
2. Select **Edit order** to return to the normal document list.

**Result:** The normal document-list controls are on screen.

If an operation displays an error or warning, continue to [When the list does not load or an action fails](#when-the-list-does-not-load-or-an-action-fails).

## When the list does not load or an action fails

Use the message on screen to identify which part of the Documents destination needs
attention.

### Recover when the category list does not load

**Prerequisites**

- A project is selected.

**Steps**

1. Follow the action for the message that appears.

   | Message | Action |
   |---|---|
   | `Loading...` | Wait for the category list to finish loading. |
   | `Authentication required` | Sign in and return to the Documents destination. |
   | `Failed to load categories` | Reload the category sidebar. |
   | `project-not-found` | Select a project that exists in the current workspace. |

**Result:** The category sidebar shows the categories for the selected project.

### Recover after reordering fails

**Prerequisites**

- A reorder action has displayed an error.

**Steps**

1. Follow the action for the message that appears.

   | Message | Action |
   |---|---|
   | `Failed to reorder documents. Please try again.` | Leave the document order unchanged, then repeat the document reorder action. |
   | `Failed to reorder categories. Please try again.` | Leave the category order unchanged, then repeat the category reorder action. |

**Result:** The requested document or category order is submitted again.

### Respond to the delete confirmation

**Prerequisites**

- The delete dialog is open for the document you intend to review.

**Steps**

1. Read `Are you sure you want to delete this document?`.
2. Read `⚠️ This action cannot be undone.`.
3. Choose the action that matches your intention.

   | If you want to… | Select |
   |---|---|
   | Close the dialog without confirming the deletion | **Cancel** |
   | Confirm the deletion after checking the document shown in the dialog | **Delete Document** |

**Result:** The dialog closes without confirmation when you select **Cancel**, or the
document deletion is confirmed when you select **Delete Document**.

## Know what to do next

After you open a saved document, continue with the page that matches the work you need
to do:

| If you need to… | Continue with… |
|---|---|
| Create a document or edit its content | [Create and edit a document](doc:create-and-edit-a-document) |
| Compare document revisions | [Compare document revisions](doc:compare-document-revisions) |
| Translate an existing document | [Translate a document](doc:translate-a-document) |
| Review document states and actions | [Document changes](doc:document-changes) |
| Read the published result | [Published documentation](doc:published-documentation) |

Opening a saved document takes you to its detail page. The detail page owns the controls
and messages for that route. The creation, revision comparison,
translation, changes, and published-documentation pages own their respective follow-on
work.