DeepDocs helps keep your documentation up-to-date by automatically syncing it with your code changes. To get the most out of DeepDocs, follow these best practices.

DeepDocs excels at updating existing documentation to reflect code changes. It is not designed to create docs from scratch.

• To document new logic, manually create an initial version of the doc.
• DeepDocs works best when docs are directly tied to code—such as:
  • API references
  • SDK guides
  • Tutorials
  • Configuration or setup instructions
  • Component or module-level docs

DeepDocs supports two modes:

• Provide up to 5 specific files from the same repo
• Use this option when you want to update specific doc files only.

• Provide a repo or subfolder as the target.
• Use this when you want DeepDocs to decide which docs to update within a folder or entire repo.

Refer the README on how to define these.

Each documentation update is marked with one of the following statuses:

• unchanged: No changes
• modified: Existing file updated
• Files marked for deletion are returned with empty content and the status modified
• Files marked for addition are appended to an existing file and also returned with the status modified

If you’ve added new logic that isn't documented yet:

• DeepDocs may try to append content to existing files.
• Instead, create a short placeholder file with description—DeepDocs will then try to update it.

DeepDocs compares against the main branch to determine changes.

• Ensure your main branch reflects the latest code and docs.
• deepdocs.yml must be committed to the main branch.

When a PR is opened:

• If docs are in the same repo, DeepDocs adds a commit to the same PR.
• If docs are in an external repo, a new PR is opened there.

Always review the doc updates:

• Check for relevance and accuracy
• Don’t approve blindly—treat docs like code

Well-structured code leads to better doc updates.

• Use descriptive function and variable names
• Keep functions focused and short
• Break logic into reusable modules

Make sure your deepdocs.yml is:

• Committed to the main branch
• Correctly specifies source_globs and either target_files or target_repo

Improper or missing configuration will result in skipped updates.

DeepDocs uses AI—while often accurate, it may:

• Misinterpret intent or context
• Hallucinate content in rare cases

Always review diffs before merging.

Let contributors know:

• DeepDocs may update docs in their PRs
• They’re responsible for reviewing those changes

By following these practices, you’ll get reliable, accurate, and maintainable documentation updates with every PR.