A Monitor watches a Source for code changes that could affect your documentation and flags the Documents that may be going stale. This page explains what a Monitor is, when it runs, and what it sends to Review.
What it is#
When you add a Source to a Library, it has two switches: Read and Monitor.
- Read lets the Library reference that Source when answering questions and writing Documents.
- Monitor watches the Source for changes worth documenting and flags Documents that may be going stale.
A Monitor is the second switch. When code changes in a monitored Source, the Monitor reads each new pull request and issue, checks the change against your published Documents, and flags the ones that fall out of date with a suggested fix. When nothing needs updating, the Monitor stays quiet.
Monitors are how Dosu keeps documentation honest as the code moves. This is the knowledge-review and stale-docs capability: catch drift early, propose a fix, and let your team approve it.
Why it matters#
Documentation rots quietly. A function is renamed, a flag is removed, an endpoint changes shape, and the page that described it is now wrong. Across many repositories and teams this is the default, and the people who knew the old context have often moved on.
A Monitor turns documentation maintenance into a side effect of normal development instead of a separate chore nobody owns. Drift gets flagged on the pull request that caused it, before the change merges. That keeps a shared source of truth current as your organization grows, and it cuts the cost of feeding coding agents stale context.
How it works#
A Monitor runs against the published Documents in a Library.
- A pull request (or merge request) is opened or marked ready for review in a monitored Source. Draft pull requests are ignored until they are ready.
- The Monitor compares the code changes against published Documents that reference the affected code.
- For each Document, it decides whether the Document is still valid, needs an update, or no longer applies.
- For anything that looks stale, it drafts a targeted edit and sends it to Review.
The Monitor also re-runs when new commits are pushed to an open pull request, with a short debounce so rapid pushes do not trigger a flood of checks. You can trigger a check on demand by commenting /dosu-refresh on the pull request.
What a Monitor produces#
When a Monitor flags a Document, your team reviews the proposal in one of two places:
- An in-PR or in-MR review comment with Accept, Edit, and Decline actions, so you can resolve drift without leaving the pull request.
- The Review page, where the same drafts are listed for approval or editing.
When a Monitor reviews a change and finds nothing to update, you choose how it signals that. It can react with an emoji, post a short comment, or stay silent.
Your decisions carry over across later commits on the same pull request, so you do not re-review the same proposal twice. See Review and Knowledge Reviews for how approval works.
Scope and requirements#
You can narrow what a Monitor watches with Monitored Paths, a set of glob patterns (for example src/** or docs/**). The default is to watch all paths. Use a narrower set to focus on the directories that map to your Documents and skip build or test files. You manage this on the Source inside its Library.
For a Monitor to flag a Document, three things must be true:
- The Document is published. Drafts and pending Documents are not watched.
- The tool is connected as a Source with Monitor turned on.
- The Library is set up to review changes (on by default).
Whether accepted edits publish automatically on merge or wait for a person is configurable. Hold updates for manual review when you want every change approved before it lands.
Turning a Monitor on#
You manage Monitors on a Source inside a Library. Open or create a Library at Libraries, add or open a Source, and turn Monitor on. From there you set how the Monitor reacts to changes and which paths trigger documentation updates.
Availability#
Monitoring code changes for documentation drift is generally available for GitHub today. Coverage for other Sources, such as GitLab and Azure DevOps, follows their availability. See Sources and the GitHub integration for connector details.
