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. Edit Strategically

When you edit a section, it becomes "human-owned" and won't be overwritten by future AI regeneration. Use this intentionally:

When to edit:
  • Critical content that must stay exactly as written
  • Company-specific information the AI can't know
  • Legal or compliance-related content
Consider leaving AI-owned:
  • API references that should update with code changes
  • Generated examples that reflect current implementation
  • Content that benefits from staying in sync with code

7. 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

8. 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

9. 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

10. 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

11. Regenerate on Major Releases

Trigger documentation regeneration when you ship significant changes:

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

12. 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