Approval workflow

Track documentation pages by approval status to ensure changes are reviewed before publishing.

Plan: Enterprise

Overview

The approval workflow feature fosters collaboration in the documentation editor by introducing a review process. Statuses can be assigned to edited pages to help indicate whether a page is ready to be published. This helps to ensure confidence and maintain high standards in your content releases.

With approval workflow, you can:
  • Facilitate collaboration among editors with a simple review process
  • Attach a status to any edited page to indicate its position in the workflow
  • Ensure documentation changes are reviewed before publishing
  • See an overview of all changed pages by status in the Changes panel
  • Restrict publishing of unapproved pages (optional)
Approval workflow - Overview
Status overview

Draft

The page has been edited or is in the process of being edited.

Ready for review

The edits to the page are ready to be reviewed.

Request changes

The page has been reviewed and changes are required before the page is ready to be published.

Ready for publish

The changes were approved and the page is ready to be published.

Published

The page was published and there have been no new changes.

Enable approval workflow

Workflows - Settings

The approval workflow can be enabled for your design system. Once enabled, statuses can then be added to a page to indicate that a review is required, changes are needed, or that the page is ready.

To enable approval workflow:
  1. Go to the Documentation Settings / Workflows section.
  2. Toggle the option to enable approval workflow. This will activate the feature and enable statuses for all edited pages.

Restrict publishing of unapproved pages

This setting can be turned on to ensure that only approved changes can be published.

  1. Go to the Documentation Settings / Workflows section.
  2. Toggle the option to “Restrict publishing of unapproved pages” to ON. This will prevent users from publishing pages that haven’t been approved with the “Ready for publish” status.

Request a review

Workflows - request review

Any editor can request a review of content changes to a page. This facilitates a collaborative review process and ensures all changes undergo scrutiny.

You'll also see information about who requested the review.

  1. Make the necessary content changes on the desired page.
  2. Click on the Request review button to submit the page for review. The page status will change to “Ready for review”.

Review changes

Workflows - reviewing changes

Reviewers (any Editor, Admin, or Owner) can easily see which pages need to be reviewed, streamlining the workflow and ensuring timely approvals in the Review panel. Reviewers have the capability to mark pages as approved (or request changes). An approval signifies that the page is ready for publishing.

You'll also see information about who requested or approved the changes.

  1. Access pending reviews: Go to the changes panel to see a list of pages that need to be reviewed.
  2. Review changes: Open a page to review the content changes made.
  3. Approve or request changes: If the changes meet the required standards, mark the page as Ready for publish. If not, mark the page as Request changes.
Workflows - ready for publish

Publishing

Workflows - publish dialog

The publishing dialog provides a clear status of the page, indicating whether it is ready for review, awaiting changes, or ready for publish. This helps the publisher understand the current state of the page at a glance when decided whether to include it in publishing.

Publish changes for a page

Workflows - publish page

To publish changes to the current page:

  1. In the page status bar, click Publish changes.
  2. In the publish dialog, you will see the current page selected.
  3. Click Publish documentation.

Publish selected changes

Workflows - publish all
  1. In the top right corner of the documentation editor, click Publish.
  2. In the popover, click Publish documentation to open the Publish dialog.
  3. In the publish dialog, you will see all pages selected in Ready for publish.
  4. Click Publish documentation.

FAQ

Can I request a review from specific person?

Currently you cannot request a review from a specific person. If you would like to notify a reviewer, you can send them a notification by mentioning the user in a comment on the page.

Some changes do not go through the approval process and are moved to Ready for publish by default, and can not be viewed in the Changes panel.

This includes deleted pages, and changes to groups or tabbed pages.

Currently, any editor can review changes. Soon we will introduce review-specific roles to allow more fine-grained control over who can approve changes.

 

See also