# Create and edit a document

## Create and edit a document

A document is a documentation record that lives inside a project. Create one when you need a
new piece of documentation, then open its editor to change the content or its settings.
Changes to the title, content, document type, slug, category, or audiences are saved to the
record automatically.

| If you need to… | Go to |
|---|---|
| Check what you need before creating a document | [Before you start](#before-you-start) |
| Reach the document workspace | [Find the document area](#find-the-document-area) |
| Create a blank document or use a template | [Create the document](#create-the-document) |
| Change document content or settings | [Edit content and save the record](#edit-content-and-save-the-record) |
| Choose a different creation or editing route | [Handle the available branches](#handle-the-available-branches) |
| Fix a validation or saving problem | [When creation or saving goes wrong](#when-creation-or-saving-goes-wrong) |
| Continue with revisions, translation, or publishing | [What to do next](#what-to-do-next) |
| Understand how documents are organised | [Documents overview](doc:documents-overview) |
| Review document changes | [Document changes](doc:document-changes) |
| Compare revisions | [Compare document revisions](doc:compare-document-revisions) |
| Translate a document | [Translate a document](doc:translate-a-document) |
| Read published documentation | [Published documentation](doc:published-documentation) |

![Select a blank document or a template from the New Document page.](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/15489835f969276c38bc1d4d5f01f51b.png)

## Before you start

Prerequisites

Have a project available for the document. The project supplies the context in which its
categories and documentation are organised.

Collect the following information before you begin:

| Information | What to prepare |
|---|---|
| Project | The project in which the document belongs |
| Category | An optional category, or the root level when no category is needed |
| Title | The name readers will use for the document |
| Slug | A lowercase, hyphenated URL-friendly identifier |
| Document Type | One of `Manual`, `Generated`, `Hybrid`, `Wiki`, `API Guide`, `User Manual`, or `SOP` |
| Audiences | At least one of `TECHNICAL`, `USER`, `API`, or `INTERNAL` |
| Content | The documentation text to place in the document |

You must be signed in to create a document. The **Project** list uses the available projects.
The **Category** list becomes available after you select a project; it includes
`No category (root level)` for a document at the root level. The **Audiences** choices must
contain at least one selection when you create the record.

## Find the document area

The Documents area is where you manage and organise documentation. Use it when you are starting
a new record or looking for a saved document to edit.

Prerequisites

You have a signed-in session and know whether you are creating a new document or changing a
saved one.

**Steps**

1. Open **Documents**.
2. Select **New Document** to start a record.
3. Select an existing document when you need to edit its saved content.

**Result:** You are at the new-document selection surface or at the editor for the saved document
you selected.

## Create the document

Use the creation form to enter a title, URL identifier, type, audience, and documentation content.
Choose a blank form when you want to enter the record yourself, or start from a template when
prepared content is a suitable starting point.

Prerequisites

You have a project available and the document information listed in [Before you start](#before-you-start).

**Steps**

1. Choose the route that matches how you want to begin.

   | If you want to… | Select |
   |---|---|
   | Enter a blank document | **Create blank document** |
   | Start with prepared content | A template in **All Templates** |

2. In **Project**, select the project for the document.
3. In **Category**, select a category, or select `No category (root level)`.
4. In **Title**, enter the document name.
5. In **Slug**, enter a lowercase, hyphenated identifier.
6. In **Document Type**, select `Manual`, `Generated`, `Hybrid`, `Wiki`, `API Guide`,
   `User Manual`, or `SOP`.
7. In **Audiences**, select at least one of `TECHNICAL`, `USER`, `API`, or `INTERNAL`.
8. In **Content**, enter the documentation text.
9. Select **Create document**.

If you leave **Title**, Slug, or **Project** empty, the page displays
`Title, slug, and project are required.`
If you clear every audience, the page displays `At least one audience is required.`
If the session has no user, the page displays `No user found. Please log in again.`

**Result:** The record is created and the page routes to its edit page. While the record is being
created, the button reads `Creating...`. If creation fails, the page displays `Failed to create document`.

## Edit content and save the record

The edit page is the workspace for changing a document's content and metadata. Its main editor
holds the document text, while the settings area holds the document type, slug, category, and
audience choices.

Prerequisites

You have opened a saved document in its edit page.

**Steps**

1. Select **Untitled Document** at the top of the editor and enter the new document title.
2. In **Content**, change the documentation text.
3. Select **Settings**, then change **Document type**, **Slug**, or **Category** as needed.
4. In **Target audiences**, select or clear the audiences that should receive the document.
5. Read the save status as `Unsaved`, wait for `Saving...`, and wait for `✓ Saved`.
6. Select **Done** when you have finished editing.

The content editor provides controls for headings, lists, quotes, tables, links, images, code
blocks, front matter, directives, and other editor functions. In the editor, the content area
uses the placeholder `Start writing your document...` when it is empty.

**Result:** The edited record shows `✓ Saved`. Keep the editor open for the available branches,
or select **Done** to return to the Documents area.
If an update fails, the page displays `Failed to save document` and the status returns to
`Unsaved`.

## Handle the available branches

The creation and editing routes change what you see according to the project, document, and
editing state. Collaborative mode handles content separately from the page's metadata save.
Use the branch that matches the state shown on your page.

Prerequisites

You are at the new-document selection page or have opened a saved document in the editor.

**Steps**

1. Choose the branch that matches what you need to do.

   | If you need to… | Action | What you see next |
   |---|---|---|
   | Start from prepared content | Select a template in **All Templates**. | The form is prefilled with the template's title, slug, content, type, and audiences. |
   | Wait for projects | Wait for `Loading projects…` to finish. | Select **Project** when the list is ready. |
   | Create the first project | Select **Create project** and create a project. | You can create the document inside the project. |
   | Select the project | Select **Project**. | The category list begins loading. |
   | Wait for categories | Wait for `Loading categories...` to finish. | Select **Category** when the list is ready. |
   | Use the root level | In **Category**, select `No category (root level)` when the page shows `No categories available`. | The document remains at the root level. |
   | Edit collaboratively | Select **Collaborate**. | Continue editing in collaborative mode. |
   | Preview for an audience | Select **Preview mode**, then choose audiences in **View as:**. | The document is shown for the selected audiences. |
   | Copy or open a published address | Use **Public URL** to copy or open the address. | The page displays `URL copied to clipboard!` after copying. |
   | Send a published public edit for review | Select **Propose change →**. | The page displays `You are editing a published page. Saving creates a change request for review — the live page keeps serving until it is merged.` |

**Result:** You are using the creation or editing route that matches the project and document
state, with the applicable fields and actions visible.

## When creation or saving goes wrong

Use the message on screen to choose the corrective action.

| What you see | What it means | What to do |
|---|---|---|
| `Loading projects…` | The project list is still loading. | Wait for the list to finish loading. |
| `No project yet.` | No project is available for the document. | Select **Create project** and create a project first. |
| `Select a project first to see categories` | A project has not been selected. | Select a project in **Project**. |
| `Loading categories...` | Categories for the selected project are loading. | Wait for the category list to finish loading. |
| `No categories available` | The selected project has no categories. | Leave **Category** at `No category (root level)`. |
| `No user found. Please log in again.` | The signed-in user is unavailable to the creation request. | Sign in again, then retry creation. |
| `Title, slug, and project are required.` | One or more required creation values are empty. | Complete **Title**, Slug, and **Project**. |
| `At least one audience is required.` | No audience is selected. | Select at least one audience in **Audiences**. |
| `Failed to create document` | The creation request failed. | Check the values and retry **Create document**. |
| `Loading document…` | The saved document is still loading. | Wait for the editor to load. |
| `Failed to load document` | The document request failed while loading. | Return to **Documents** and open the document again. |
| `Document failed to load.` | The editor could not load the document. | Select **Back to documents**, then open the document again. |
| `Saving...` | An update is being sent. | Wait for the status to change. |
| `Unsaved` | The latest change has not finished saving. | Wait for `✓ Saved` before leaving the editor. |
| `Failed to save document` | The update request failed. | Retry the edit and wait for `✓ Saved`. |

## What to do next

After the record is saved, continue according to the outcome you need:

| If you need to… | Continue with |
|---|---|
| Review the record's states and available actions | [Document changes](doc:document-changes) |
| Compare versions or revisions | [Compare document revisions](doc:compare-document-revisions) |
| Translate the document | [Translate a document](doc:translate-a-document) |
| Read the public version | [Published documentation](doc:published-documentation) |

**Result:** You have a saved document record and a clear next document task.