https://docs.all-hands.dev/ logo
Join Slack
Powered by
As a thought experiment, I was thinking how we cou...
# proj-documentation
l
As a thought experiment, I was thinking how we could restructure our App docs to look like the Devin docs, which IMO are a bit easier to follow than ours. I actually think it’s not too hard if we think this way: 1. GUI (as represented by app.all-hands.dev) and CLI are the two main use cases, and each workflow we document should be documented for GUI and CLI users if there is a difference between the two. 2. Everything else is an “integration”, including current github, gitlab, bitbucket, slack, and future integration into other editors using ACP If we do that, then we could have: 1. Getting Started 2. Using OpenHands Effectively 3. Onboarding a Codebase 4. Advanced Features 5. Integrations Each one could be flat single-level menu.
cc @elegant-branch-54423 and @better-park-34863 for comment
e
I think those are good high level sections
Maybe we spin up a doc to enumerate the sub-pages for each section?
I kinda want to see the full ToC for my own sanity
b
What do you mean GUI (as represented by app.all-hands.dev)? GUI for OpenHands Cloud with the getting started and its integrations are vastly different than GUI (running on your own). Which I believe is why you had suggested we split the docs with OpenHands Cloud and Running locally sections
l
Yeah, I think basically we can have two suggested ways of using OpenHands for beginners: GUI on cloud and CLI locally. Everything else could be an advanced option.
b
Even GUI by yourself is advanced in this scenario? Even though it's the default?
c
Last I know, we thought like 80% of users use Web GUI
👍 1
l
Yeah, I think not so many people use the GUI locally anymore. At least not any of the maintainers that I know of
(other than for development)
b
So depends who the docs is for. Most issues and Discord are still for the GUI
c
Ah, Graham, that sounds to me like a serious problem that maybe AH could fix?
I meant above 80% of users, of the people who use OpenHands, the Open Source project. I mean, deprecating that seems... very odd
👍 1
(Please don't get me wrong, maybe something like that is the future... and I can see some reasons for it to be honest, but it seems like... not a too near future perhaps 🤔 )
b
I've thought about the docs a lot. The number of ways that OH can be run, doesn't make this easy. OpenHands Cloud -> Sort of the same as running GUI locally, but the important parts like integrations and setting up and getting started are all different so they need documenting. OpenHands GUI (running locally) -> This is the default for people not wanting to use the Cloud. And getting started and connecting repos is different than Cloud. OpenHands CLI -> Different thing. If you look at the current docs, everything under 
OpenHands Cloud
is unique to the Cloud instant. I haven't looked at 
Run OpenHands on your Own
in a while because V1 and I didn't know where we want to go with it. It might make sense to split that into GUI locally and CLI.
l
I think it’s a good question, but honestly I don’t think it’s anywhere close to 80% on GUI, it seems that most of the issues on github are for CLI or headless?
c
Are they?
l
Just browsed the most recent 20 by non-maintainers and it seems that over half are
c
According to Mamoodi above,
Most issues and Discord are still for the GUI
l
I’ll ask OpenHands to do a closer analysis though
e
Mahmoud, lets chat about some of our ideas here. In general, the goal is to better organize the docs to make it easier to navigate. I do think we need to account for the different ways of using OH: Cloud, Local GUI, CLI, SDK.
👍 1
b
Regardless I think GUI locally still needs to be documented on how to run and configure it. If that understanding is incorrect and we don't want that, then all I've said is wrong.
👍 1
l
Yeah, I totally agree with that! But I think it’s also possible that this could be viewed as a bit more “advanced” since it’s generally a bit more complex than the other two options. I’ll try to collect a bit more data on this though
Ideally we want the onboarding experience in the docs to be extremely simple so we don’t lose people who get confused
c
@limited-student-10747 Just to note, two more thoughts: Last I know, Robert's blog pointed out that AH splits its work roughly 50/50 with Open Source / proprietary software. • I honestly don't understand if that changed and how to square that with the idea that no maintainers test the app-server ? • most of app-server is worked on and Open Source, afaik. Are we building that for practically no one to use? Visual interfaces are a big part of UX. Since early 2025 Claude Code took the world by storm, CLIs had an amazing revival. But most of the features are still built on GUI (app server) and there's a lot of people afaik that don't really like CLIs 🤔
👍 1
b
The way that Joe has it in the proposed docs is how we had it originally. And then it was decided that because things are becoming complicated, we should split it the way we have now. So essentially: • Ways to do X ◦ GUI ◦ CLI ◦ Cloud • Ways to do Y ◦ GUI ◦ CLI ◦ Cloud or • CLI ◦ How to do X ◦ How to do Y • GUI ◦ How to do X ◦ How to do Y • Cloud ◦ How to do X ◦ How to do Y Whatever you think is easier to follow, I'm with it!
c
I think the second, most of the time? People who use OpenHands use OpenHands from a particular interface
e
To be clear, we will document how to use all ways of using OH. This feedback is helping in understand how folks want/need the docs organized. We are very much committed to supporting our open source users and want to make sure the docs are easy and clear to follow for all 🙏
The outline in the word doc isn’t set in stone, we are open to changing it!
We are trying to make things better, not worse 😁
b
My suggestion is layout all the docs how you want them with all the different scenarios and ways to run OH included. Just the title obviously. Then see how it looks at the high level. Because it's when you account for all the ways, that things get confusing. I found after Graham suggested the split and implementing it, that people complained less about the docs. However, I'm not in total know of everything so happy to chat about it and see where the issues are coming from
c
Thank you, Joe, I don't doubt that!
🙌 1
l
Yeah, to just organize my thinking here a bit: I think if we have two ways of doing things in parallel it’s probably manageable, probably three starts to get unmanageable. Fortunately we have SDK docs separate now so we can get rid of “headless” as a way of running things. Ideally I’d like to have only “GUI and CLI”. I realize that local GUI is a bit different, but in many cases it’s pretty similar and its functionality is now largely in parallel of what’s available on the cloud. So we can possibly consolidate to just GUI and CLI. Happy to chat about this later as well!
c
Just to note, lately Mamoodi has moved a bunch of issues from OH to agent-sdk. At least some of those were GUI
b
Ah Graham, I think the part we are not in sync is that for me, OpenHands Cloud GUI is quite different than GUI locally. Looking at the current docs, many of them only apply to Cloud or GUI locally but not both. Everything under 
OpenHands Cloud
-> Only Cloud Everything under 
Run OpenHands on Your Own
-> Only Local I would LOVE to actually have only two ways of running OH 😄
l
I would LOVE to actually have only two ways of running OH 😄
Me too, although maybe it’s too aspirational 🙂
🙏 1
Anyway, thanks, I’ll think about it a bit more!
🙏 1
c
I hear the call to simplicity, but if we want two sections, then idk, how about a structure like: CLI • CLI docs here Web UI • Web UI (OpenHands) ◦ when something is different on Cloud, "Note: on Cloud is is [link] or not available"
Actually... Maybe another bit that may be worth thinking about is the tabs to be maybe like: 
OpenHands / SDK / Cloud / REST API / SDK API / Success Stories
p
LangChain seems to do a good job in their docs highlighting which of their services are open source, free, or paid, with pretty diagrams; early in the self-onboarding docs flow is the underlying need that paying customers get lost in the current docs?
lolsob 1
l
The underlying need is that right now a lot of the core functionality in OpenHands is harder to find, like how to onboard a repo effectively. People’s patience with docs is very low, so making information as easy as possible to find in the top-level sidebar seems important.
c
nod I agree I actually suggest to move out the first three links out of the sidebar, which are not exactly _technical documentation_: • Company • Blog • Cloud (link to the app) I think they typically are found in top menu or footer menu, not sidebar
l
Yeah, I suggested that too but according to Xingyao it’s a bit tricky to do with mintlify. We can probably just remove them if they’re hard to move elsewhere
🙏 1
But totally agree
c
I’m looking at Joe’s document, and all I see is a ToC with OpenHands features. (not cloud) I actually think maybe the suggestion above is worth considering: to put Cloud in its own tab. Please let me try to think this over a bit, from basics. Tab: App OpenHands has two main interfaces / applications: • Web GUI • CLI There we have things you can do: (Joe’s toc) Tab: SDK • SDK stuff Tab: Cloud • Cloud-specific stuff • Cloud is an application built on OpenHands, of course many OH features are present, but they were documented at their original source. (App) • afaik the Cloud is meant much more for enterprise / as B2B, than for “consumers” • this matters, because it also means it’s going to get more org-specific features, that only muddy the view if they’re mixed in the App tab
l
Personally I think it’d probably be better to mainly organize around “things you can do with the openhands app”, and maybe have tags like “CLI/Cloud GUI/Local GUI” about which things that are supported in each place. I think generally people approach things from the POV of “what I want to do” instead of “which piece of software should i use”
Also, IMO I don’t really view the cloud as being drastically different than the local GUI, I think probably 80-90% of the things you can do with the app you can do in both places (ofc there are some features only available on the cloud, and vice-versa as well)
c
My point with that is that usually, people looking for docs on something, are already using OpenHands. So they are using OpenHands via a particular interface. Most people don't switch all of them, I don't think (although some of us do 😅)
l
Ah, that might be the underlying disconnect: I’d love the docs to be useful for people who aren’t using openhands yet but want to
p
Why not keep just "OpenHands", and when a section applies to "Cloud" simply tag it like GitLab tags Premium and Enterprise offerings
l
Why not keep just “OpenHands”, and when a section applies to “Cloud” simply tag it like GitLab tags Premium and Enterprise offerings
Yeah, that’s my suggestion above
c
p
e.g.: https://docs.gitlab.com/ci/pipelines/merge_trains/ Merge trains • Tier: Premium, Ultimate • Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated on all their docs; I never got lost in their stuffy docs; it always felt clear I think the key is to do it consistently everywhere
l
Yeah, and this is “what i want to do”
I think GitLab is a great template actually
c
I hear you on being also clear if you don't know yet what you want to use, just see what OpenHands can do: in that case, I feel that • "OpenHands", as in mainly the Web App (open source web app) has most answers ◦ a note in places could substract some stuff if running on the cloud • a Cloud tab could contain the added specifics of cloud deployment
b
In the example of "I want to onboard my codebase", how would the tagging look like in the cases where the process is different between OpenHands Cloud, Local GUI and CLI? Do you create different pages? Or do you have one page that has three different sections?
l
Things like “creating repo.md” and “creating skills” are basically the same I think. So they would overlap.
b
This might be a controversial take but if our app and CLI is not self explanatory enough that the core functionality is not clear to the user, then we need to make that better in the app/CLI. As you mentioned, patience for docs is very low. People don't really read docs to know how to get started with an AI tool such as OH. It should be pretty clear.
👍 2
l
I agree that optimizing our onboarding for the CLI and GUI are both great too
p
https://nuxt.com/docs/4.x/getting-started/installation#new-project you could add tabs that dynamically change the whole docs to switch to the in-context users have
l
@better-park-34863 for the core question, maybe for those situations
how would the tagging look like in the cases where the process is different between OpenHands Cloud, Local GUI and CLI?
I think in a very limited number of cases, we could have three sections or separate sub-pages. But these could be very limited
p
Here's another example I like: https://www.pulumi.com/docs/iac/get-started/kubernetes/create-project/ When I primarily write a Node/TypeScript Pulumi program, I choose the TypeScript tab, and all documentation pages keep that context if I write a Go or a Python Pulumi program, I change the language, and voila, "personalized docs" in my current language of choice; it's fun to read through these docs actually... For OpenHands, there might be CLI/Web/Cloud "tabs" (to change docs contexts) to adapt the docs to current situation the user finds themselves in Going for a docs design like this would focus the docs on a use-case; not the mechanism (CLI vs. Web vs. Cloud - because you can achieve the same thing 3+ different ways with OpenHands)
👍 2
b
Yeah that's nice actually. The tabs feature in mintlify can be used heavily to split the specific use-case based on how you are using OpenHands. It might get a little ugly at times but if we want to do based on "I want to do X", that would be the best one I can think of as well. Don't know if mintlify would have a global toggle so that it automatically chooses the one you're currently looking for or we'd have to somehow manage that.
g
Late to the convo, I know but going through in depth here
Most issues and Discord are still for the GUI
@better-park-34863 is this GUI locally to confirm please?
, people looking for docs on something, are already using OpenHands
Yes @limited-student-10747 and @calm-artist-7206 i anticipate we will launch some sort of OpenHands University style resource that the express purpose will be to onboard people. Then the docs are more of a reference for current users. I am investigating how to strike a balance for now as I research the best way to overhaul these docs. Thank you all for sharing these thoughts, I am capturing them in eval of hwo to improve our docs
c
Yes, this is very important IMO: • as far as I know, Web UI via local docker is by far, by far, the most popular / common way of using OH If Graham or anyone has doubts about it, let's talk. Let's gather data if we can. It's a significant discrepancy if we think of this point differently.
e
Engel, I very much agree. And we will continue to support local Web UI docs. There’s a lot of additional documentation on how to use the local Web UI that we want to make available (and better organized, too — which I think it one of the main goals of this)
c
Cool, thank you! It's a factual point, mainly, though, so we can find out in some way, right?
b
My current understanding is that local GUI is the most used scenario. However, I don’t have concrete data to back that up. Though in our README of the main OpenHands repo, that is the default really.
c
Just to add some detail, though it's just downloads. Also, the move of the repo changed the docker packages, so it restarted the download count. FWIW though, according to GitHub: • first is All-Hands-AI/packages: 3 million • second is OpenHands/packages: 7k / 34k in three weeks, apparently The "openhands" package is the App, the local docker OH web app. It's the default in the README that Mamoodi refers to. (I have no idea how many users that means, since obviously many users, and their uses, imply multiple downloads, and there might be more confounding factors. 🤷‍♂️)
l
Yeah, but I think those are downloaded by the OpenHands cloud as well every time someone uses it?
I could try to get some numbers
🙏 1
Open in Slack
PreviousNext
Powered by