Documentation review
Documentation review checks your published help articles against your product and tells you which ones to read first. It works on projects marked as product documentation, and it has two parts: a review page per project, which compares articles with the screens in your app, and an optional reviewer that checks your docs when code changes merge.
Neither part hands you a verdict. The checks are good at deciding what a person should look at first, and not reliable enough to say an article is wrong, so every finding is a lead for you to confirm.
Before you start:
- Your workspace needs an AI provider chosen under Settings > AI, either Workover AI (included with a paid plan) or Your own key. See Choose who provides Workover AI.
- For the review page, the project must be marked as product documentation (step 1 below). The merge reviewer does not need this.
- For the review page, your app must be connected under Settings > Integrations > Screenshots. See Product screenshots in drafts.
- For Fix with Workover AI and the merge reviewer, a code repository must be linked to the project. See Grounding drafts in your code repository.
Warning: Checks and fixes are AI calls. On Your own key, they bill to your provider account, and a larger documentation project costs more to check.
Review a project’s articles
- Open the project, select Project settings, and set What this project holds to Product documentation, then select Save changes.
- In the project, select Review. The Documentation review page opens.
- Select Check these articles now to check up to 50 articles straight away, or wait for the weekly check. Progress shows as “N of M articles checked”.
- Work down the page from the top. Articles are grouped by what the check found, most urgent first.
- For an article with findings, read the quoted sentences and the reason given for each. Open the product to confirm before changing anything.
To have Workover AI correct an article, select Fix with Workover AI under it. Workover AI reads the linked repository and corrects only what the code shows is wrong.
Suggested edit ready: open the article to accept or reject it. means the corrections are waiting in the article as tracked suggestions.
Checked against the code: nothing to change. The finding did not hold up. means the code did not support the finding.
What the groups mean
| Group | Meaning |
|---|---|
| Names a control the product does not have | The article tells readers to use a button, field or menu that was not found in your app. Settle these first. |
| A check disagreed with the article | The check thinks the article and the product differ. Worth opening the product to confirm; right about half the time. |
| We could not check it | The check failed on Workover’s side. Nothing here is a statement about the writing. |
| Never checked | Nothing has looked at these articles yet. |
| Nothing here a screen could settle | Prose rather than instructions, so there is nothing a screenshot of the product could confirm. |
| Checked, and still agrees | The last check found nothing wrong. |
The weekly check covers up to 25 articles per project, starting with the ones checked longest ago, so in a large project it is a rotating sample rather than every article. Release notes are never checked, because they record what shipped rather than how the product works today.
Troubleshooting
| Message | What to do |
|---|---|
| Connect your product first, so there is something to check against. | Connect your app under Settings > Integrations > Screenshots. |
| Your product is connected but has not been crawled yet. That runs weekly. | Wait for the weekly scan of your app, then check again. Saving new Start pages on the app connection also scans it again. |
| No crawl of your product yet, so nothing has been checked against its controls. | Same as above: the review has no screens to compare with yet. |
| This project has no linked repository, so there is nothing to check the article against. Link one in Project settings. | Fix with Workover AI needs a linked repository. Link one under Project settings > Linked repositories. |
| Review does not appear in the project | The project is not marked as Product documentation. See step 1. |
Check docs when code merges
The Documentation reviewer checks whether a merged pull request made any published document wrong, and raises the corrections as one change request to review. It is off until you turn it on.
- Go to Settings > AI and, under AI features, turn on Documentation reviewer. A workspace owner or admin can change this.
- Make sure the project has a GitHub repository linked under Project settings > Linked repositories, with the Workover GitHub app installed on the account that owns it. See GitHub.
- Optional: in the same Linked repositories card, choose the branch under Review documentation on. Leave it on Default branch to follow the repository’s default branch.
- Optional: turn on Review pull requests too to get suggestions while a pull request is still open. This runs a review on every push to a pull request, not once per merge, so it costs more.
When the reviewer raises corrections, you get a Documentation review notification for each document, for example ““Webhooks” may be out of date, with one suggested edit”. Opening it shows the suggested edits to review.
These settings are not available for a repository linked with Link public repo, or for one on GitLab or Bitbucket, because Workover gets no merge signal from them.
Related
Still need help?
Can’t find what you’re looking for? Our team is here to help.