Getting started with Moxie Docs

Overview

In a few minutes, you will connect a GitHub repository, let Moxie Docs scan for documentation drift, and open your first focused docs pull request. You’ll see “PR opportunity” cards that summarize what fell out of date and can create a ready-to-review documentation PR.

What you need

• A GitHub account with access to at least one repository you can install apps on or request installation for.
• Permission to install a GitHub App on the target repository or organization, or an admin who can approve it.
• A Moxie Docs workspace where you can connect repositories.

Steps

1. Open Moxie Docs Go to the Docs dashboard in your Moxie workspace. You’ll land on the Docs dashboard where repositories and PR opportunities appear after connection.

2. Connect your GitHub repository Start the GitHub connection flow from the Docs dashboard. You will be asked to install the Moxie GitHub App on the repositories you want Moxie Docs to analyze. After you finish installation on GitHub, you’ll return to Moxie Docs.

3. Select repositories to analyze Choose the repository you want to start with. Moxie Docs records your selection and begins the initial scan.

4. Wait for the initial scan to complete Stay on the Docs dashboard while Moxie analyzes recent code changes and documentation. When finished, the PR opportunities section shows cards grouped by repository.

5. Review PR opportunities In the PR opportunities section, look for cards under your connected repository. Each card summarizes a drift finding such as stale docs, undocumented APIs, orphaned pages, or convention mismatches.

6. Open details for a finding Click a card to view details. You’ll see why it was flagged and the suggested updates aligned to your repository’s conventions.

7. Open a focused docs PR Click Open PR on a card to create a focused GitHub pull request with the suggested documentation updates. The PR includes one consolidated, auto‑updating guidance comment to keep the description consistent with your conventions.

8. Review the pull request on GitHub Open the PR on GitHub, read the changes, and confirm the guidance comment. Make any edits you need. Nothing is published without your approval.

9. Merge the docs update When you’re satisfied, approve and merge the PR in GitHub. Your documentation is now updated to match the code.

10. Tidy up or tune findings (optional) Back on the Docs dashboard, workspace owners or admins can hide low‑value drift findings from the PR opportunities section permanently or for a set time window, and undo this later. You can also adjust per‑repo automation like which drift detectors are enabled, PR description alignment guidance, and recap comments on PRs.

What’s next

• Review and manage drift findings in the PR opportunities section to keep docs current over time.
• Use Ask this codebase in the Docs → Ask panel to answer repo‑grounded questions and leave thumbs feedback to improve results.
• Fine‑tune per‑repo automation settings to match your team’s conventions and notification preferences.
• Invite teammates to your workspace so they can review PRs and manage drift together.

If something goes wrong

• If you don’t see PR opportunities after connecting, wait a few minutes and refresh the Docs dashboard to allow the initial scan to finish.
• If GitHub App installation is blocked, ask an organization owner to install the app on the target repository and then return to Moxie Docs.
• If a drift card looks low‑value or noisy, use hide to remove it temporarily or permanently; you can undo this later in the Docs dashboard.