DRAFT - Work in Process - Restructure docs navigation #271
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This PR restructures the OpenHands documentation navigation to better align with Devin.ai's documentation structure. Key changes include: ## Navigation Changes - **Merge CLI and Web tabs** into a single 'Documentation' tab - **Create new 'Use Cases' tab** with tutorials, examples, and prompt library - **Rename 'SDK' tab to 'API Reference'** and integrate REST API docs - **Add 'Best Practices' section** mirroring Devin's Essential Guidelines ## New Pages Added ### Best Practices (4 pages) - When to Use OpenHands - Writing Effective Instructions - Good vs Bad Instructions - Integrations Overview ### Use Cases Section (15 pages) - Overview and Best Practices - Examples: Code Migrations, Test Coverage, Bug Fixing, Documentation, Refactoring, API Integration - Tutorials: Getting Started, REST API, Test Coverage, Containerization, Frontend Development - Prompt Library: Testing & Refactoring, Data Analysis, Web Development ## Structure Comparison | New Tab | Content | |---------|---------| | Getting Started | Intro, Quick Start, First Projects, FAQs, Community | | Documentation | Merged CLI+Web: Setup, Running, Integrations, Features, Settings | | Use Cases | Examples, Tutorials, Prompt Library (NEW) | | API Reference | SDK, Guides, Architecture, Python & REST APIs | Co-authored-by: openhands <openhands@all-hands.dev>
Changes: - Rename 'API Reference' tab back to 'SDK' (exact copy of original structure) - Move 'Best Practices' section from Documentation to Getting Started - Create new 'OpenHands Cloud' tab with: - Cloud getting started pages (openhands-cloud, cloud-ui, cloud-api, cli/cloud) - Cloud integrations (GitHub, GitLab, Bitbucket, Slack, Project Management) - REST API (openapi/openapi.json) - Remove Cloud-related content from Documentation tab - Simplify Integrations in Documentation to just overview and MCP servers Co-authored-by: openhands <openhands@all-hands.dev>
jpelletier1
changed the title
jpelletier1
changed the title
The redirect from /sdk to /sdk/index was conflicting with the tab navigation, causing too many redirects error when clicking on SDK tab. Co-authored-by: openhands <openhands@all-hands.dev>
Added comprehensive gap analysis to docs-navigation-proposal.md: ## HIGH PRIORITY Gaps (Critical for user success): - Your First Session - step-by-step guide for first interaction - SDLC Integration - how OpenHands fits into dev workflows - Workspace & Session Tools - understanding IDE, Browser, Shell - Repository Setup Guide - comprehensive repo configuration ## MEDIUM PRIORITY Gaps: - Limitations & Best Fit Tasks - Playbooks / Reusable Prompts - Slash Commands (if applicable) - Ask Mode / Q&A Mode - Session Insights / Analytics ## LOWER PRIORITY Gaps: - Advanced Mode / Batch Sessions - Deployments - PR Templates - Security Practices - Common Issues Also documented which pages were already created in this PR. Co-authored-by: openhands <openhands@all-hands.dev>
Navigation changes: - Move Use Cases tab to right after Documentation - Rename GUI Server to Local GUI, position under Terminal (TUI) - Make Web Interface a sub-page of Terminal (TUI) - Move OpenHands Cloud page as sub-page of Terminal (TUI) - Add redirect from gui-server to local-gui New HIGH priority pages: - Your First Session: Step-by-step first interaction guide - SDLC Integration: How OpenHands fits in development lifecycle - Workspace & Session Tools: Understanding workspace and tools - Repository Setup Guide: Configuration for test/lint/build commands New MEDIUM priority pages: - Limitations & Best Fit Tasks: Capabilities and constraints - Playbooks & Reusable Prompts: Template prompts for common tasks Co-authored-by: openhands <openhands@all-hands.dev>
|
Looks like there are a few issues preventing this PR from being merged!
If you'd like me to help, just leave a comment, like Feel free to include any additional details that might help me get this PR into a better state. You can manage your notification settings |
Contributor
Author
|
Closing this. Restarting a new plan and series of conversations here: #272 |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Summary
This PR restructures the OpenHands documentation navigation to better align with Devin.ai's documentation structure. The goal is to make the docs more intuitive and comprehensive for users.
Key Changes
Navigation Structure
New Tab Structure:
New Pages Added (19 total)
Best Practices Section (4 pages)
openhands/usage/tips/when-to-use-openhands.mdx- When OpenHands is most effectiveopenhands/usage/tips/effective-instructions.mdx- How to write clear instructionsopenhands/usage/tips/good-vs-bad-instructions.mdx- Examples of effective promptsopenhands/usage/integrations/overview.mdx- Central hub for all integrationsUse Cases Section (15 pages)
Overview:
use-cases/overview.mdx- Use cases landing pageuse-cases/best-practices.mdx- Best practices for each use case typeExamples:
use-cases/examples/code-migrations.mdxuse-cases/examples/test-coverage.mdxuse-cases/examples/bug-fixing.mdxuse-cases/examples/documentation.mdxuse-cases/examples/refactoring.mdxuse-cases/examples/api-integration.mdxTutorials:
use-cases/tutorials/getting-started.mdxuse-cases/tutorials/rest-api.mdxuse-cases/tutorials/test-coverage.mdxuse-cases/tutorials/containerization.mdxuse-cases/tutorials/frontend-development.mdxPrompt Library:
use-cases/prompts/testing-refactoring.mdxuse-cases/prompts/data-analysis.mdxuse-cases/prompts/web-development.mdxCLI/Web Merge Strategy
For the merged Documentation tab, pages will use consistent callouts:
<Callout type="note" title="CLI Only"><Callout type="note" title="Cloud/Web Only">Preview
After merging, the new navigation should display the restructured tabs. Mintlify will automatically build and deploy the preview.
Related Analysis
This restructure was based on a detailed comparison with Devin.ai's documentation:
Next Steps (Future PRs)
@jpelletier1 can click here to continue refining the PR