DRAFT - Work in Process - Initial layout of new doc structure by jpelletier1 · Pull Request #284 · OpenHands/docs

jpelletier1 · 2026-01-30T01:20:50Z

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

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

- incident-triage.mdx: Add content based on Datadog debugging blog post - Features automated error analysis with OpenHands SDK - Includes GitHub Actions workflow for Datadog integration - Links to blog: https://openhands.dev/blog/debugging-production-issues-with-ai-agents-automating-datadog-error-analysis - cobol-modernization.mdx: Add content based on COBOL-to-Java refactoring blog post - Features iterative refinement approach with multiple agents - Includes code transformation examples (COBOL to Java) - Links to blog: https://openhands.dev/blog/20251218-cobol-to-java-refactoring - vulnerability-remediation.mdx: Add content based on vulnerability fixer documentation - Explains automated vulnerability remediation with AI agents - Links to example implementation at github.com/OpenHands/vulnerability-fixer - Covers integration with security scanners (Snyk, Dependabot, CodeQL) - dependency-upgrades.mdx: Remove redundant security scanning section - Links to Vulnerability Remediation page for security-related upgrades - Focuses on general dependency upgrade workflows Co-authored-by: openhands <openhands@all-hands.dev>

- Rename from 'TODO-Tutorial Library' to 'Tutorial Library' - Remove 'Getting Started with Tutorials' section - Add Note linking to Use Cases section for in-depth guidance - Add Code Review cross-references: - Link to Code Review Use Case page - Link to PR Review SDK Guide (sdk/guides/github-workflows/pr-review) - Add Bug Fixing cross-reference to Incident Triage Use Case Co-authored-by: openhands <openhands@all-hands.dev>

Replace tabs-based layout with a card-based design: - OpenHands Cloud (recommended) - links to https://app.all-hands.dev - Local GUI - links to /openhands/usage/run-openhands/local-setup - Terminal / CLI - links to /openhands/usage/cli/installation Each card includes relevant icons and bullet points highlighting key features. Co-authored-by: openhands <openhands@all-hands.dev>

openhands-ai · 2026-02-05T22:41:22Z

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 · 2026-02-19T16:22:20Z

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

openhands-ai · 2026-02-19T16:22:43Z

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

Sync openhands/usage/use-cases/code-review.mdx with the updated version from main that includes the Software Agent SDK-based PR review workflow documentation.

openhands-ai · 2026-02-19T16:24:03Z

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 · 2026-02-19T17:26:42Z

@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 · 2026-02-19T17:27:05Z

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

These links were duplicated in the Additional Documentation section when they already exist under V0 Reference in the same navigation. Co-authored-by: openhands <openhands@all-hands.dev>

openhands-ai · 2026-02-19T17:28:38Z

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 · 2026-02-19T17:31:38Z

@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/usage/essential-guidelines/good-vs-bad-instructions.mdx

openhands/usage/essential-guidelines/sdlc-integration.mdx

openhands/usage/essential-guidelines/when-to-use-openhands.mdx

openhands-ai · 2026-02-19T17:31:58Z

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

neubig · 2026-02-19T17:32:20Z

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

openhands-ai · 2026-02-19T17:32:41Z

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

- Created new 'OpenHands Community' section below 'Additional Documentation' - Moved 'Developers' group from Additional Documentation to OpenHands Community - Moved 'Community' group from Additional Documentation to OpenHands Community Co-authored-by: openhands <openhands@all-hands.dev>

openhands-ai · 2026-02-19T17:33:40Z

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

- Update SDLC integration intro text - Add Linear task management reference - Add codecov module reference - Add codecov re-run guidance - Add Continuous Integration section with links to integrations - Remove empty Note block at end of file - Add detailed guidance on when to use OpenHands with specific task types Co-authored-by: openhands <openhands@all-hands.dev>

openhands-ai · 2026-02-19T17:36:15Z

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.

- Updated Dependency Updates use case - Removed 'TODO-' on some pages - Updated Community section - Removed $10 references

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.

all-hands-bot · 2026-02-19T18:00:52Z

openhands/usage/essential-guidelines/when-to-use-openhands.mdx

+But it can be particularly useful for certain types of tasks. For instance:
+
+- **Clearly Specified Tasks:** Generally, if the task has a very clear success criterion, OpenHands will do better. It is especially useful if you can define it in a way that can be verified programmatically, like making sure that all of the tests pass or test coverage gets above a certain value using a particular program. But even when you don't have something like that, you can just provide a checklist of things that need to be done.
+- **Highly Repetitive Tasks:** These are tasks that need to be done over and over again, but nobody really wants to do them. Some good examples include code review, improving test coverage, upgrading dependency libraries. In addition to having clear success criteria, you can create "[skills](TODO)" that clearly describe your policies about how to perform these tasks, and improve the skills over time.


🔴 Critical: TODO placeholder needs to be replaced with an actual link.

Suggested change

- **Highly Repetitive Tasks:** These are tasks that need to be done over and over again, but nobody really wants to do them. Some good examples include code review, improving test coverage, upgrading dependency libraries. In addition to having clear success criteria, you can create "[skills](TODO)" that clearly describe your policies about how to perform these tasks, and improve the skills over time.

- **Highly Repetitive Tasks:** These are tasks that need to be done over and over again, but nobody really wants to do them. Some good examples include code review, improving test coverage, upgrading dependency libraries. In addition to having clear success criteria, you can create "[skills](/overview/skills)" that clearly describe your policies about how to perform these tasks, and improve the skills over time.

all-hands-bot · 2026-02-19T18:00:53Z

openhands/usage/essential-guidelines/sdlc-integration.mdx

+    types: [opened, labeled]
+  pull_request:
+    types: [opened, synchronize]
+  issue_comment:
+    types: [created]
+
+jobs:
+  auto-review:
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: OpenHands PR Review
+        uses: openhands/review-action@v1
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+
+  issue-triage:
+    if: github.event_name == 'issues' && contains(github.event.issue.labels.*.name, 'needs-analysis')
+    runs-on: ubuntu-latest
+    steps:
+      - uses: openhands/triage-action@v1
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+```


🟠 Important: These GitHub Actions (openhands/review-action@v1, openhands/triage-action@v1) appear to be hypothetical examples rather than published actions.

Add a note clarifying this is an example workflow pattern, or link to actual working actions if they exist. Users might try to use these directly and encounter "action not found" errors.

all-hands-bot · 2026-02-19T18:00:53Z

docs.json

+              "openhands/usage/key-features",
+              "overview/model-context-protocol",
              {
-                "group": "Integrations",
+                "group": "Skills",
                "pages": [
-                  "openhands/usage/cloud/bitbucket-installation",
-                  "openhands/usage/cloud/github-installation",
-                  "openhands/usage/cloud/gitlab-installation",
-                  "openhands/usage/cloud/slack-installation",
-                  {
-                    "group": "Project Management Tools",
-                    "pages": [
-                      "openhands/usage/cloud/project-management/jira-integration"
-                    ]
-                  }
+                  "overview/skills",


🟡 Suggestion: The "Onboarding OpenHands" section only has 2 items, and one (overview/skills/repo) is already nested under the Skills section in Product Guides.

Consider either:

Expanding this section with more onboarding content, or

Merging it into "Get Started" or "Essential Guidelines"

This would reduce navigation duplication and make the structure clearer.

Initial layout

117c950

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

jpelletier1 requested a review from mamoodi as a code owner January 30, 2026 01:20

jpelletier1 marked this pull request as draft January 30, 2026 01:20

jpelletier1 changed the title ~~Initial layout of new doc structure~~ DRAFT - Work in Process - Initial layout of new doc structure Jan 30, 2026

jpelletier1 mentioned this pull request Jan 30, 2026

DRAFT - Work in Process - Reorganize navigation #272

Closed

2 tasks

mintlify bot deployed to staging January 30, 2026 01:21 View deployment

Added content to TODO pages.

8eebf15

mintlify bot deployed to staging February 3, 2026 17:45 View deployment

mintlify bot deployed to staging February 4, 2026 16:15 View deployment

mintlify bot deployed to staging February 4, 2026 17:20 View deployment

mintlify bot deployed to staging February 4, 2026 17:22 View deployment

jpelletier1 linked an issue Feb 5, 2026 that may be closed by this pull request

Review new docs and navigation outline #294

Open

5 tasks

Calvin Smith added 6 commits February 5, 2026 12:00

minor deletions, overview rework

72bf018

re-organize sections to match flow

879790e

understanding section rewrite

72b817d

scaling up moved, rewritten

7e88ac2

validation restructure

ae53972

tranlsation rewrite

8dc8927

mintlify bot deployed to staging February 5, 2026 22:41 View deployment

spark migration rewrite, first pass

c5d3966

mintlify bot deployed to staging February 16, 2026 15:34 View deployment

Merge branch 'main' into jp/docs-restructure-0129

91b5099

mintlify bot deployed to staging February 19, 2026 15:45 View deployment

Update code-review.mdx to match main branch

4144c96

Sync openhands/usage/use-cases/code-review.mdx with the updated version from main that includes the Software Agent SDK-based PR review workflow documentation.

mintlify bot deployed to staging February 19, 2026 16:23 View deployment

Remove redundant V0 Configuration and V0 REST API links from nav

c5cca0d

These links were duplicated in the Additional Documentation section when they already exist under V0 Reference in the same navigation. Co-authored-by: openhands <openhands@all-hands.dev>

mintlify bot deployed to staging February 19, 2026 17:28 View deployment

neubig reviewed Feb 19, 2026

View reviewed changes

mintlify bot deployed to staging February 19, 2026 17:33 View deployment

mintlify bot deployed to staging February 19, 2026 17:35 View deployment

Misc updates

8ac0241

- Updated Dependency Updates use case - Removed 'TODO-' on some pages - Updated Community section - Removed $10 references

mintlify bot deployed to staging February 19, 2026 17:57 View deployment

jpelletier1 marked this pull request as ready for review February 19, 2026 17:57

all-hands-bot reviewed Feb 19, 2026

View reviewed changes

Conversation

jpelletier1 commented Jan 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

openhands-ai bot commented Feb 5, 2026

Uh oh!

jpelletier1 commented Feb 19, 2026

Uh oh!

openhands-ai bot commented Feb 19, 2026

Uh oh!

openhands-ai bot commented Feb 19, 2026

Summary

What was done:

Changes made:

Verification:

Uh oh!

jpelletier1 commented Feb 19, 2026

Uh oh!

openhands-ai bot commented Feb 19, 2026

Uh oh!

openhands-ai bot commented Feb 19, 2026

Summary

Checklist

Details

Uh oh!

jpelletier1 commented Feb 19, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

openhands-ai bot commented Feb 19, 2026

Uh oh!

neubig commented Feb 19, 2026

Uh oh!

openhands-ai bot commented Feb 19, 2026

Uh oh!

openhands-ai bot commented Feb 19, 2026

Summary

Checklist

Resulting Navigation Structure

Uh oh!

openhands-ai bot commented Feb 19, 2026

Summary

Checklist

Changes Summary

Conciseness Check

Uh oh!

all-hands-bot left a comment

Choose a reason for hiding this comment

Uh oh!

all-hands-bot Feb 19, 2026

Choose a reason for hiding this comment

Uh oh!

all-hands-bot Feb 19, 2026

Choose a reason for hiding this comment

Uh oh!

all-hands-bot Feb 19, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Comments

jpelletier1 commented Jan 30, 2026 •

edited

Loading