Keep docs in sync

Keep your docs in sync with your code, automatically. A scheduled docs audit checks whether the docs still match the code and opens a PR when they have drifted.

Goal: Keep your docs in sync with your code, automatically.

What it does

Every morning, a schedule checks whether the docs still match the code. If they have drifted and no audit PR is already open, it opens a PR with the fix. This catches the common kind of rot where someone changes an API but forgets to update the docs, so the docs quietly go stale.

The plugin

tessl/docs-audit reads the code and the docs, finds where they disagree, and opens a PR that reconciles them. Install it with:

$ tessl install tessl/docs-audit

Define the schedule

Run it every day at 7:00 UTC. Add this entry to the schedules block in your project's tessl.json, and keep any other entries already in that block. Replace production with the name of your environment (see the Schedules overview for the prerequisites).

1

Add the schedule entry

{
  "schedules": {
    "docs-audit": {
      "skill": "tessl/docs-audit",
      "schedule": "daily at 07:00",
      "environment": "production"
    }
  }
}

2

Validate and push

Validation always checks the local file. For an authenticated linked project that can reach Tessl, it also gives an advisory warning when current workspace capacity may not accommodate additional schedules. Commit and push the change, then confirm Tessl applied the schedule in your workspace before checking its run history.

$ tessl schedule validate
$ git add tessl.json
$ git commit -m "chore(docs): add docs audit schedule"
$ git push

3

Check the runs

Open the schedule in the web app, or run tessl schedule runs <id> to see its run history.

Customize with instructions

Scope the audit to the part of the docs that drifts most by adding instructions to the same schedule entry. Keep all other entries in the schedules block:

{
  "schedules": {
    "docs-audit": {
      "skill": "tessl/docs-audit",
      "schedule": "daily at 07:00",
      "environment": "production",
      "instructions": "Only check the API reference against the route handlers in src/api"
    }
  }
}

Create your own

Want a different behavior? Create your own plugin that reads the code and the docs and reconciles them your way.