Keeping your documentation in sync with your product releases is crucial. By versioning your documentation, you can maintain separate, accurate guides for different releases (like v1.0 and v2.0) simultaneously, ensuring all your users have the right information for the version they are using.

How versioning works

Your documentation is structured hierarchically. Each documentation project can have multiple Versions. Inside each version, you organize content into Sections, which contain individual Doc Entries (the actual pages your users read).

flowchart TD
    Doc[Documentation Project] --> V1["Version 1.0"]
    Doc --> V2["Version 2.0"]
    
    V2 --> S1["Section: Getting Started"]
    V2 --> S2["Section: API Reference"]
    
    S1 --> E1["Doc Entry: Installation"]
    S1 --> E2["Doc Entry: Quickstart"]

Version statuses

To help users navigate your documentation, you can assign specific statuses to your versions to indicate their lifecycle stage:

Managing your documentation lifecycle

Whether you are preparing for a major new release or just making a small patch, the workflow for managing versions remains consistent.

1. 1

   Create a new version

   Start by creating a new version (for example, v2.0). This creates an isolated space where you can draft updates without affecting your live documentation.

2. 2

   Organize sections and entries

   Build out your navigation by creating Sections. You can easily reorder these sections to ensure a logical flow. Then, populate the sections with your Doc Entries.

3. 3

   Update version settings

   Once your content is ready, you can update the version's status. For a new major release, you might set it as both the Latest and Default version.

4. 4

   Publish your changes

   Trigger a publish job to push your new version live. Publishing runs in the background, ensuring your live site remains fast and responsive.

Publishing and monitoring

Publishing documentation is handled through background jobs. When you are ready to share your updates, you initiate a Publish Job.

Because large documentation sites can take a moment to build, you can monitor the progress of your deployments:

• Check job status: View the current state of an ongoing publish job to see when it finishes.

• View publish history: Look back at previous publish jobs to audit when changes went live.

• Get latest publish: Quickly retrieve the details of the most recently completed publish.

Managing versions via API

If you prefer to manage your documentation lifecycle programmatically, you can use our REST API. The following endpoints are available for version management: