Best Practices

Get the most out of Git2Docs by following these recommendations for your codebase and documentation workflow.

Codebase Preparation

1. Maintain a Good README

Your README is the primary signal Git2Docs uses to understand your product. A well-structured README helps the AI generate more accurate documentation.

Tip: Include these sections in your README:
  • What the product does (one-liner)
  • Key features or capabilities
  • Installation/setup instructions
  • Basic usage examples
  • Links to more documentation

2. Use Meaningful Names

Function names, variable names, and file names all contribute to the AI's understanding. Descriptive naming helps generate better explanations.

// Good - intent is clear
function calculateOrderTotal(items, discountCode) { ... }

// Less helpful - requires reading implementation
function calc(i, d) { ... }

3. Add Code Comments Strategically

While Git2Docs can infer behavior from code, comments help with:

  • Explaining why something works a certain way
  • Documenting edge cases and constraints
  • Noting important business rules

Don't over-comment obvious code, but do explain non-obvious decisions.

4. Organize Code Logically

A well-organized codebase is easier for both humans and AI to understand:

  • Group related files in directories
  • Use consistent naming conventions
  • Separate concerns (API, business logic, data access)

Documentation Workflow

5. Review AI-Generated Content

While Git2Docs generates high-quality documentation, human review ensures accuracy. Pay special attention to:

  • Low confidence sections - These benefit most from verification
  • Technical accuracy - Verify code examples and commands work
  • Tone and voice - Ensure it matches your brand
  • Completeness - Add any missing context

6. Refine with Tell AI, edit only as a last resort

The primary refinement loop is Tell AI: leave feedback on the sections that read wrong, click Submit Review, Apply. Claude consolidates your batch into a brief patch + page-regen queue, so the AI fixes things across the docs in one pass instead of you correcting the same issue twenty times.

Hand-edit a section only when the change is surgical and not worth a Claude call — typo, a tweaked sentence, a one-off example. Hand edits flip the section to human_ownedand AI regeneration will leave it alone going forward.

Use Tell AI when:
  • The fix touches more than one section ("change the CLI prefix everywhere")
  • You want the brief to learn — so the AI gets it right on the next regen too
  • Validator findings need to be batched into doc fixes
Hand-edit when:
  • You need a surgical word change a Claude call would be overkill for
  • The content must be exact (legal language, customer-specific copy)
  • The AI keeps re-introducing a wrong phrasing the brief can't capture

7. Validate against the live product before publishing

Tier 0 validation runs automatically on every regen — it catches flags / endpoints / response codes that don't exist in the source. Tier 1 validation is opt-in: paste the prompt URL into a coding agent (Claude Code recommended; Codex / Antigravity work with the same URL), let it exercise every documented CLI + API call against your live deployment, then upload the findings JSON. Click Tell AI on the real failures, Submit Review, Apply. The docs converge on reality without you rewriting them by hand.

Run Tier 1 at least once before flipping new docs from draft to public. It's the cheapest insurance against a customer opening a support ticket for a documented endpoint that doesn't exist.

8. Resolve Contests Promptly

When AI detects changes that affect human-owned content, it creates a "contested" state. Review these promptly to keep documentation current:

  • Accept AI version - If the code change should update the docs
  • Keep human version - If your content is still correct
  • Merge manually - Combine insights from both versions

Portal Configuration

9. Configure Branding

Set up your company branding to create a professional documentation portal:

  • Company logo - Appears in header and portal
  • Product name - Used in page titles
  • Accent color - Applied to links and highlights
  • Copyright info - Appears in footer

10. Use Custom Domains

Point your docs subdomain (e.g., docs.yourcompany.com) to your Git2Docs portal for a seamless branded experience. This:

  • Builds trust with users
  • Improves SEO for your documentation
  • Provides a professional appearance

11. Organize Multiple Products

If your organization has multiple products, each can have its own documentation space while sharing the same portal:

  • Connect multiple repositories
  • Each gets its own branded card on the portal
  • Users can easily navigate between products

Maintenance

12. Regenerate on Major Releases

Trigger documentation regeneration when you ship significant changes:

  • New features or APIs
  • Changed workflows or interfaces
  • Deprecated functionality

13. Monitor Generation Progress

Use the progress panel in the dashboard to monitor documentation generation. If generation fails, check:

  • Repository access permissions
  • Branch/tag availability
  • Error messages in the progress log