Keep documentation healthy as code changes.
DocHeal is an early Coding Moves Lab project. The idea is simple: when code changes, help maintainers find the docs that may need another look.
Imagine an API field changes from user_name to display_name, but a guide still tells readers to use user_name. That guide has drifted from the code. DocHeal should point to the change and the guide so a person can decide what to fix. It should not silently rewrite the page or pretend it can prove every document correct.
This is an idea-stage repository. There is no checker, CLI, package, or test suite yet. The repository contains the project direction, an MIT license, and contributor guidance. The starter issues lay out the first pieces of work. Nothing here is a released DocHeal tool.
The proposed first check is small: compare two local Git revisions of a Python argparse CLI file, then flag a removed long option still named in an inline code span in a specified Markdown guide. The design note shows when it should report a possible problem, when it should stay quiet, and what it will not cover.
The checker and its command do not exist yet. The report format and command syntax still need to be designed. The local check should work without an AI key or a hosted service.
If that proves useful, we can consider more checks, repository configuration, and a GitHub pull request integration. AI-assisted analysis might help with harder cases later, but it would be optional. Findings should always give maintainers enough evidence to review them, and any GitHub integration should use only the permissions it needs.
There is nothing to install or run today. Read this README and CONTRIBUTING.md, then look at the starter issues. The good first issues are small documentation tasks that do not need an unfinished checker.
If you have seen documentation drift in a real project, open an issue and describe the code change, the stale documentation, and what a useful warning would say. Please remove private details. For a problem with this repository or its docs, choose the bug report form.
Small, self-contained examples are especially helpful. The examples guide explains the format. Before a large pull request, discuss the behavior in an issue so we agree on the scope. Please read our Code of Conduct as well.
- Define the first supported drift case and inputs.
- Gather more positive examples and cases that should stay quiet.
- Define a clear finding and report format.
- Build and test the first local check.
- Document real commands, configuration, and limits once they exist.
- Explore pull request checks after the local workflow is useful.
DocHeal will stay in Coding Moves Lab while we test the idea. After a first working release, we plan to move its website listing to Coding Moves Open Source.
- Documentation drift: When documentation no longer matches the actual code or current project behavior.
- Finding: A reported issue that may indicate a problem in the documentation.
- Source reference: A pointer to the code or other source material used to check whether documentation is accurate.
- Documentation reference: A pointer to the part of the documentation being discussed or checked.
- False positive: A reported finding that is not actually a problem.
Suppose a guide still says to use --user-name after the code removes that option. This is possible documentation drift. A future finding could point to the removed option in the code (the source reference) and the old option in the guide (the documentation reference). If the guide mentions the old option on purpose, that finding would be a false positive.
DocHeal does not run this check yet; these terms describe the planned workflow.
DocHeal is licensed under the MIT License.