Update start building doc

index.mdx

@@ -1,6 +1,6 @@
 ---
 title: Introduction
-description: OpenHands - Code Less, Make More
+description: OpenHands - Code Less, Make More.
 icon: book-open
 mode: wide
 ---

openhands/usage/start-building.mdx

@@ -4,97 +4,128 @@ description: So you've [run OpenHands](/openhands/usage/quick-start). Now what?
 icon: code
 ---
 
-OpenHands can assist with a range of engineering tasks. However, the technology is still new, and we’re far from having
-agents that can handle complex tasks independently. It’s important to understand what the agent does well and where it
-needs support.
+Like any tool, it works best when you know how to use it effectively. Whether you're experimenting with a small
+script or making changes in a large codebase, this guide will show how to apply OpenHands in different scenarios.
 
-## Hello World
+Let’s walk through a natural progression of using OpenHands:
+- Try a simple prompt.
+- Build a project from scratch.
+- Add features to existing code.
+- Refactor code.
+- Debug and fix bugs.
 
-Start with a simple "hello world" example. It might be trickier than it seems!
+## First Steps: Hello World
 
-Prompt the agent with:
+Start with a small task to get familiar with how OpenHands responds to prompts.
+
+Click `New Conversation` and try prompting:
 > Write a bash script hello.sh that prints "hello world!"
 
-The agent will write the script, set the correct permissions, and run it to check the output.
+OpenHands will generate script, set the correct permissions, and even run it for you.
+
+Now try making small changes:
 
-You can continue prompting the agent to refine your code. This is a great way to
-work with agents. Start simple, and iterate.
+> Modify hello.sh so that it accepts a name as the first argument, but defaults to "world".
 
-> Modify hello.sh so that it accepts a name as the first argument, but defaults to "world"
+You can experiment in any language. For example:
 
-You can also use any language you need. The agent may need time to set up the environment.
+> Convert hello.sh to a Ruby script, and run it.
 
-> Please convert hello.sh to a Ruby script, and run it
+<Info>
+  Start small and iterate. This helps you understand how OpenHands interprets and responds to different prompts.
+</Info>
 
-## Building From Scratch
+## Build Something from Scratch
 
-Agents excel at "greenfield" tasks, where they don’t need context about existing code and
-they can start from scratch.
+Agents excel at "greenfield" tasks, where they don’t need context about existing code.
 Begin with a simple task and iterate from there. Be specific about what you want and the tech stack.
 
-For example, we might build a TODO app:
+Click `New Conversation` and give it a clear goal:
 
 > Build a frontend-only TODO app in React. All state should be stored in localStorage.
 
-Once the basic structure is in place, continue refining:
+Once the basics are working, build on it just like you would in a real project:
 
 > Allow adding an optional due date to each task.
 
-Just like normal development, commit and push your code often.
-This way you can always revert back to an old state if the agent goes off track.
-You can ask the agent to commit and push for you:
+You can also ask OpenHands to help with version control:
 
-> Commit the changes and push them to a new branch called "feature/due-dates"
+> Commit the changes and push them to a new branch called "feature/due-dates".
 
-## Adding New Code
+<Info>
+  Break your goals into small, manageable tasks.. Keep pushing your changes often. This makes it easier to recover
+  if something goes off track.
+</Info>
 
-OpenHands is great at adding new code to an existing codebase.
+## Expand Existing Code
 
-For instance, you can ask OpenHands to add a GitHub action that lints your code. It might check your codebase to
-determine the language, then create a new file in `./github/workflows/lint.yml`.
+Want to add new functionality to an existing repo? OpenHands can do that too.
 
-> Add a GitHub action that lints the code in this repository.
+<Note>
+If you're running OpenHands on your own, first add a
+[GitHub token](/openhands/usage/run-openhands/gui-mode#github-setup),
+[GitLab token](/openhands/usage/run-openhands/gui-mode#gitlab-setup) or
+[Bitbucket token](/openhands/usage/run-openhands/gui-mode#bitbucket-setup).
+</Note>
+
+Choose your repository and branch via `Open Repository`, and press `Launch`.
+
+Examples of adding new functionality:
 
-Some tasks need more context. While OpenHands can use commands like ls and grep to search, providing context upfront
-speeds things up and reduces token usage.
+> Add a GitHub action that lints the code in this repository.
 
 > Modify ./backend/api/routes.js to add a new route that returns a list of all tasks.
 
 > Add a new React component to the ./frontend/components directory to display a list of Widgets.
 > It should use the existing Widget component.
 
-## Refactoring
+<Info>
+  OpenHands can explore the codebase, but giving it context upfront makes it faster and less expensive.
+</Info>
+
+## Refactor Code
 
-OpenHands does great at refactoring code in small chunks. Rather than rearchitecting the entire codebase,
-it's more effective to break up long files and functions or rename variables.
+OpenHands does great at refactoring code in small chunks. Rather than rearchitecting the entire codebase, it's more
+effective in focused refactoring tasks. Start by launching a conversation with
+your repo and branch. Then guide it:
 
 > Rename all the single-letter variables in ./app.go.
 
 > Split the `build_and_deploy_widgets` function into two functions, `build_widgets` and `deploy_widgets` in widget.php.
 
 > Break ./api/routes.js into separate files for each route.
 
-## Bug Fixes
+<Info>
+  Focus on small, meaningful improvements instead of full rewrites.
+</Info>
+
+## Debug and Fix Bugs
 
-OpenHands can help track down and fix bugs, but bug fixing can be tricky and often requires more context.
-It’s helpful if you’ve already diagnosed the issue and just need OpenHands to handle the logic.
+OpenHands can help debug and fix issues, but it’s most effective when you’ve narrowed things down.
+
+Give it a clear description of the problem and the file(s) involved:
 
 > The email field in the `/subscribe` endpoint is rejecting .io domains. Fix this.
 
 > The `search_widgets` function in ./app.py is doing a case-sensitive search. Make it case-insensitive.
 
-For bug fixing, test-driven development can be really useful. You can ask the agent to write a new test and iterate
+For bug fixing, test-driven development can be really useful. You can ask OpenHands to write a new test and iterate
 until the bug is fixed:
 
 > The `hello` function crashes on the empty string. Write a test that reproduces this bug, then fix the code so it passes.
 
-## More
+<Info>
+  Be as specific as possible. Include expected behavior, file names, and examples to speed things up.
+</Info>
+
+## Using OpenHands Effectively
 
 OpenHands can assist with nearly any coding task, but it takes some practice to get the best results.
 Keep these tips in mind:
 * Keep your tasks small.
-* Be specific.
-* Provide plenty of context.
+* Be clear and specific.
+* Provide relevant context.
 * Commit and push frequently.
 
-See [Prompting Best Practices](/openhands/usage/tips/prompting-best-practices) for more tips on how to get the most out of OpenHands.
+See [Prompting Best Practices](/openhands/usage/tips/prompting-best-practices) for more tips on how to get the most
+out of OpenHands.