DRAFT - Work in Process - Initial layout of new doc structure

[jpelletier1]

This is an initial layout that roughly mimics Devin docs. It attempts to separate Documentation and Use Cases.

Some background:

• The structure attempts to provide better onboarding docs and "first time user experience" docs.
  • This initial pass is mostly a mapping of existing content; there are some pages we may want to design
  • Features that are common across all interfaces (like Skills, MCP, Secrets, etc.) have their own standalone pages
• The OSS projects have some additional sections dedicated for them
  • Local GUI docs can be found under Documentation > Additional Docs > Local GUI
  • CLI docs also have their own section under Documentation > CLI
  • SDK remains its own tab, unchanged
• OpenHands Cloud can be found under Product Guides > OpenHands Cloud. There's more opportunity to build this out.

TODO:

• Pages marked TODO- are stubbed out but need more content

• Content is needed under the "Use Cases" tab

• Redesign the "Quick Start" page

• I have read and reviewed the documentation changes to the best of my ability.

• If the change is significant, I have run the documentation site locally and confirmed it renders as expected.

Summary of changes

[openhands-ai]

Looks like there are a few issues preventing this PR from being merged!

• GitHub Actions are failing:
  • Check Broken Links
  • .github/workflows/sync-agent-sdk-openapi.yml
  • .github/workflows/sync-docs-code-blocks.yml

If you'd like me to help, just leave a comment, like

@OpenHands please fix the failing actions on PR #284 at branch `jp/docs-restructure-0129`

Feel free to include any additional details that might help me get this PR into a better state.

_{^{You can manage your notification settings}}

[jpelletier1]

@OpenHands please update this branch to use this same file on main: openhands/usage/use-cases/code-review.mdx

[openhands-ai]

I'm on it! jpelletier1 can track my progress at all-hands.dev

[openhands-ai]

Summary

I have successfully completed the requested update to PR #284.

What was done:

• ✅ Updated openhands/usage/use-cases/code-review.mdx to match the version from the main branch
• ✅ Changes have been committed and pushed to the jp/docs-restructure-0129 branch

Changes made:

The file was replaced from a TODO stub version with the complete documentation from main that includes:

• Software Agent SDK-based PR Review workflow documentation
• Quick Start setup guide
• Composite Action details and configuration options
• Repository-specific customization instructions
• Security considerations
• Example reviews and troubleshooting information

Verification:

• Request addressed: ✅ The single file requested was updated to match main
• Changes concise: ✅ Only 1 file modified (208 insertions, 349 deletions) - exactly as requested
• Pushed to remote: ✅ Commit 4144c96 pushed to origin/jp/docs-restructure-0129

[jpelletier1]

@OpenHands Please remove the following links in the nav as they are redundant / already used in other places

• Advanced Configuration > V0 Configuration
• Advanced Configuration > V0 REST API

[openhands-ai]

I'm on it! jpelletier1 can track my progress at all-hands.dev

[openhands-ai]

Summary

I have successfully completed the requested changes to PR #284.

Checklist

• ✅ Removed "V0 Configuration Options" group from the Additional Documentation section
• ✅ Removed "V0 REST API" group from the Additional Documentation section
• ✅ Changes are concise - only 10 lines removed, all directly related to the requested removal
• ✅ Changes already pushed to the jp/docs-restructure-0129 branch

Details

The removed navigation items were redundant because they already exist under the "V0 Reference" group within the same "Additional Documentation" section (lines 159-183 in the original file). The commit (c5cca0d) removes only the duplicate entries while preserving the primary V0 Reference section that contains the same content.

[jpelletier1]

@OpenHands Let's create a new section below "Additional Documentation" called "OpenHands Community". Move all pages under "Additional Documentation > Community" to that new section. Also move "Additional Documentation > Developers" to that new section/

[openhands-ai]

I'm on it! jpelletier1 can track my progress at all-hands.dev

[neubig]

@OpenHands check and reflect the comments by neubig. When they are reflected, mark the comments as resolved through the graphql API.

[openhands-ai]

I'm on it! neubig can track my progress at all-hands.dev

[openhands-ai]

Summary

I have successfully completed the requested changes to PR #284.

Checklist

• ✅ Created new "OpenHands Community" section - Added as a new group below "Additional Documentation" in the Documentation tab
• ✅ Moved "Developers" group - Transferred from Additional Documentation to OpenHands Community (includes: development-overview, debugging, websocket-connection, evaluation-harness)
• ✅ Moved "Community" group - Transferred from Additional Documentation to OpenHands Community (includes: community, contributing, faqs, feedback)
• ✅ Changes are concise - Only modified docs.json with minimal structural changes (6 insertions, 1 deletion)
• ✅ Changes already pushed to the jp/docs-restructure-0129 branch

Resulting Navigation Structure

Documentation Tab
├── ...
├── Additional Documentation
│   ├── V0 Reference
│   ├── Local GUI
│   └── LLM Configuration
└── OpenHands Community  ← NEW SECTION
    ├── Developers
    └── Community

[openhands-ai]

Summary

I have successfully completed the requested task to check and reflect neubig's comments on PR #284.

Checklist

• ✅ Fetched all review comments by neubig - Found 9 review comments/threads
• ✅ Applied all suggestions to sdlc-integration.mdx:
  • Updated intro text to mention "example prompts"
  • Added Linear task management reference with LINEAR_API_KEY
  • Added "using the codecov module" reference
  • Added paragraph about re-running codecov
  • Added new "Continuous Integration" section
  • Removed the Note block at end of file
• ✅ Applied suggestion to when-to-use-openhands.mdx:
  • Replaced the original Note with comprehensive guidance on task types where OpenHands excels and struggles
• ✅ Changes committed and pushed to jp/docs-restructure-0129
• ✅ All 9 review threads resolved via GitHub GraphQL API

Changes Summary

• 2 files changed: sdlc-integration.mdx and when-to-use-openhands.mdx
• 31 insertions, 10 deletions

Conciseness Check

All changes directly correspond to neubig's specific suggestions - no extraneous modifications were made. Each edit was a direct implementation of a review comment suggestion.

The branch has been successfully pushed and all review threads have been marked as resolved through the GraphQL API.

[all-hands-bot]

Taste Rating: 🟡 Acceptable - Good content and improved structure, but some organizational issues and incomplete references need attention.

Verdict: ✅ Worth merging after addressing the critical TODO and clarifying the GitHub Actions examples.

[neubig]

@OpenHands reflect the comment above about hypothetical docs, and also check/fix the broken links CI

[openhands-ai]

I'm on it! neubig can track my progress at all-hands.dev

[openhands-ai]

Final Summary

I have successfully completed all requested tasks for PR #284:

Changes Made

1. Removed hypothetical GitHub actions from sdlc-integration.mdx (per neubig's comment)

• Removed fake openhands/review-action@v1 and openhands/triage-action@v1 references
• Replaced the entire CI/CD Integration section with links to real SDK documentation
• Removed the second hypothetical openhands/triage-action@v1 in the Event-Triggered Workflows section
• Net result: -160 lines of hypothetical examples, +25 lines linking to real documentation

2. Fixed broken link in dependency-upgrades.mdx (fixing CI)

• Changed /openhands/usage/admin/security → /sdk/guides/security

3. Resolved PR review thread

• Resolved thread PRRT_kwDOPqI_Z85vm-qG via GraphQL API

Verification Checklist

• ✅ Hypothetical GitHub actions removed (neubig's main request)
• ✅ Real SDK documentation linked instead
• ✅ Broken links CI now passes (mint broken-links returns success)
• ✅ All neubig's review threads resolved
• ✅ Changes are concise (only 2 files modified, directly addressing the issues)
• ✅ Changes committed and pushed to jp/docs-restructure-0129 branch

Commit

5729ad5 - Address neubig's review comments: remove hypothetical GitHub actions and fix broken link

The PR should now pass the "Check Broken Links" CI workflow once it re-runs.

[neubig]

I have reviewed "good-vs-bad-instructions", "sdlc-integration", "when-to-use-openhands", "incident-triage", and "vulnerability-remediation" and they seem good enough for now.

I'll update "vulnerability-remediation" later when I have some content prepared for it.

[jpelletier1]

@neubig Thanks - should we wait for the vulnerability-remediation edits before shipping?