GH Onboarding has wrong screenshots

[aravindputrevu]

Hi, a customer shared the feedback over onboarding doc in github. I observed that we have not added steps for adding repositories and we also added the wrong screenshot of self hosted in step 1 instead of SaaS.

Slack Message

[linear]

ENG-1741 GH Onboarding has wrong screenshots

[traycerai]

Plan

Observations

I found the GitHub onboarding documentation issues mentioned in the ticket. The main problem is in /docs/platforms/github-com.md where Step 1 uses a self-hosted GitHub screenshot (login-self-hosted-github.png) instead of a SaaS screenshot for the GitHub.com onboarding flow. Additionally, the repository addition steps lack detailed instructions and screenshots, making the onboarding process incomplete for users trying to add repositories to their CodeRabbit integration.

Approach

I'll fix the GitHub onboarding documentation by:

1. Correcting the screenshot issue: Replace the incorrect self-hosted screenshot in Step 1 of the GitHub.com guide with the appropriate SaaS login screenshot
2. Enhancing repository addition steps: Add comprehensive step-by-step instructions for adding repositories with proper screenshots and detailed guidance
3. Improving the overall flow: Ensure the onboarding process is complete and user-friendly by adding missing steps and clarifying existing ones

The changes will focus on making the GitHub.com onboarding documentation accurate and comprehensive for SaaS users.

Reasoning

I analyzed the GitHub ticket describing wrong screenshots in the GitHub onboarding documentation. I searched for GitHub-related onboarding files and found the issue in /docs/platforms/github-com.md where Step 1 incorrectly uses a self-hosted GitHub screenshot instead of a SaaS screenshot. I also identified that the repository addition steps need enhancement with more detailed instructions and appropriate screenshots.

Proposed File Changes

📄 /docs/platforms/github-com.md ^(NEW) 🔗

References

• 📄 /docs/platforms/github-enterprise-server.md
• 📄 /docs/getting-started/quickstart.md

Fix the incorrect screenshot in Step 1 by replacing the self-hosted GitHub login screenshot with the appropriate SaaS login screenshot. The current screenshot path /img/integrations/login-self-hosted-github.png should be changed to use a SaaS-specific screenshot like /img/integrations/login-github-saas.png or /img/integrations/login-github-com.png.

Enhance the repository addition section (Step 4) by:

• Adding detailed step-by-step instructions for adding repositories
• Including screenshots for the repository selection process
• Providing clear guidance on repository permissions and authorization
• Adding instructions for both "Install on all repositories" and "Select repositories" options
• Including screenshots of the GitHub repository access dialog
• Adding guidance on what happens after repository installation

Improve the overall onboarding flow by:

• Adding more context about what users should expect at each step
• Including troubleshooting tips for common issues
• Ensuring all steps have appropriate visual aids
• Making the repository addition process more prominent and detailed

Diagram

sequenceDiagram
    participant User
    participant CodeRabbit
    participant GitHub
    participant Documentation
    
    User->>Documentation: Access GitHub.com onboarding guide
    Documentation->>User: Show Step 1 with CORRECT SaaS screenshot
    User->>CodeRabbit: Click "Login with GitHub"
    CodeRabbit->>GitHub: Redirect to GitHub authorization
    GitHub->>User: Show authorization page
    User->>GitHub: Authorize CodeRabbit
    GitHub->>CodeRabbit: Return with authorization
    CodeRabbit->>User: Show organization selection
    User->>CodeRabbit: Select organization
    CodeRabbit->>User: Show dashboard
    Documentation->>User: Show DETAILED repository addition steps
    User->>CodeRabbit: Add repositories (with clear instructions)
    CodeRabbit->>GitHub: Request repository access
    GitHub->>User: Show repository selection dialog
    User->>GitHub: Select repositories and install
    GitHub->>CodeRabbit: Grant repository access
    CodeRabbit->>User: Confirm successful integration

Loading

Import In IDE

🤖 Prompt for AI Agents

I have created the following plan after thorough exploration and analysis of the codebase. Follow the below plan verbatim. Trust the files and references. Do not re-verify what's written in the plan. Explore only when absolutely necessary. First implement all the proposed file changes and then I'll review all the changes together at the end. Make sure you fix all the linting, compilation or validation issues after successful implementation of the plan.

### Observations

I found the GitHub onboarding documentation issues mentioned in the ticket. The main problem is in `/docs/platforms/github-com.md` where Step 1 uses a self-hosted GitHub screenshot (`login-self-hosted-github.png`) instead of a SaaS screenshot for the GitHub.com onboarding flow. Additionally, the repository addition steps lack detailed instructions and screenshots, making the onboarding process incomplete for users trying to add repositories to their CodeRabbit integration.

### Approach

I'll fix the GitHub onboarding documentation by:

1. **Correcting the screenshot issue**: Replace the incorrect self-hosted screenshot in Step 1 of the GitHub.com guide with the appropriate SaaS login screenshot
2. **Enhancing repository addition steps**: Add comprehensive step-by-step instructions for adding repositories with proper screenshots and detailed guidance
3. **Improving the overall flow**: Ensure the onboarding process is complete and user-friendly by adding missing steps and clarifying existing ones

The changes will focus on making the GitHub.com onboarding documentation accurate and comprehensive for SaaS users.

### Reasoning

I analyzed the GitHub ticket describing wrong screenshots in the GitHub onboarding documentation. I searched for GitHub-related onboarding files and found the issue in `/docs/platforms/github-com.md` where Step 1 incorrectly uses a self-hosted GitHub screenshot instead of a SaaS screenshot. I also identified that the repository addition steps need enhancement with more detailed instructions and appropriate screenshots.

## Mermaid Diagram

sequenceDiagram
    participant User
    participant CodeRabbit
    participant GitHub
    participant Documentation
    
    User->>Documentation: Access GitHub.com onboarding guide
    Documentation->>User: Show Step 1 with CORRECT SaaS screenshot
    User->>CodeRabbit: Click "Login with GitHub"
    CodeRabbit->>GitHub: Redirect to GitHub authorization
    GitHub->>User: Show authorization page
    User->>GitHub: Authorize CodeRabbit
    GitHub->>CodeRabbit: Return with authorization
    CodeRabbit->>User: Show organization selection
    User->>CodeRabbit: Select organization
    CodeRabbit->>User: Show dashboard
    Documentation->>User: Show DETAILED repository addition steps
    User->>CodeRabbit: Add repositories (with clear instructions)
    CodeRabbit->>GitHub: Request repository access
    GitHub->>User: Show repository selection dialog
    User->>GitHub: Select repositories and install
    GitHub->>CodeRabbit: Grant repository access
    CodeRabbit->>User: Confirm successful integration

## Proposed File Changes

### /docs/platforms/github-com.md(NEW)

References: 

- /docs/platforms/github-enterprise-server.md
- /docs/getting-started/quickstart.md

Fix the incorrect screenshot in Step 1 by replacing the self-hosted GitHub login screenshot with the appropriate SaaS login screenshot. The current screenshot path `/img/integrations/login-self-hosted-github.png` should be changed to use a SaaS-specific screenshot like `/img/integrations/login-github-saas.png` or `/img/integrations/login-github-com.png`.

Enhance the repository addition section (Step 4) by:
- Adding detailed step-by-step instructions for adding repositories
- Including screenshots for the repository selection process
- Providing clear guidance on repository permissions and authorization
- Adding instructions for both "Install on all repositories" and "Select repositories" options
- Including screenshots of the GitHub repository access dialog
- Adding guidance on what happens after repository installation

Improve the overall onboarding flow by:
- Adding more context about what users should expect at each step
- Including troubleshooting tips for common issues
- Ensuring all steps have appropriate visual aids
- Making the repository addition process more prominent and detailed

---

Developer Humor

🖼️ A screenshot worth a thousand words,
But the wrong one causes user herds!
Self-hosted shown for SaaS flow,
Made customers say Oh no!
Now fixed, the docs sing like birds! 🐦✨

---

Execution Information

Branch: main
Commit: 3c3a995

---

💡 Tips

Supported Commands (Inside Comments)

• Use @traycerai generate to iterate on the previous version of the implementation plan.

Supported Commands (Inside Description)

• Add @traycerai ignore anywhere in the ticket description to prevent this ticket from being processed.
• Add @traycerai branch:<branch-name> anywhere in the ticket description to specify the target branch for the implementation plan.

Community

• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.