[Docs] Comprehensive Getting Started Documentation

[rorychatterton]

If you've never used Buck2 before, the path to productive is pretty steep. I think we could make the documentation a bit clearer for users who sit outside of the Meta Ecosystem.

The documentation, while very comprehensive, is somewhat overwhelming and confusing if you are unfamiliar with development practices around Monorepo, or lack context to the facebook way of doing things (tools, testing, release, etc).

It would be good if the documentation had a section (perhaps for a handful of languages) that takes you somebody through the lifecycle of zero to hero (no project, to something running with internal and external dependencies), and migration from local tooling (Cargo, Gradle, Poetry, etc) into Buck2.

It would be good to get a bit of a user narrative that takes you through things like:

• What does the developer workflow with buck look like
• What languages have first class support, vs those which need work
• Clarity on the boundaries of what buck should, and shouldn't orchestrate (e.g. Without knowing what tpx is, I have no idea what the handoff is meant to be, or what the simple runner does, or how this plugs into a release tool.)
• What tools/ides are supported, and what is the path of least resistance (e.g. does it have a strong affinity for nix, vscode - Rustup has no plugin support, etc).
• Any dependencies to make life easier (e.g. normally partnered with Sapling, or similar)
• How to build your first library
• How to build your first running binary
• How to migrate dependencies into Buck (e.g. Reindeer Fixups is confusing as heck)
• How to test it (This actually took a bit of digging to figure out how the heck to get rust tests to actually work). It would be good to see what 'good' looks like as you layer in testing tools
• Where remote execution come into play, and how this tool is expected to work in small, medium, and larger teams (i.e. developer lifecycle)
• How to extend buck
• What sorts of things you would expect to do with Buck on day 2.
• Buck anti-patterns
• What things shouldn't be done with Buck (e.g. As an outsider, I was naively expecting to see strong coverage of JS/React)

I appreciate this isn't exclusive, and that many of these segments are answered individually - but I think reducing the friction to get a user to productive would go a long way for uptake, and is probably stuff I imagine exists in the internal meta repo.

I'm happy to have a go at putting together a bit of a skeleton of information on the side, but lack context on the happy path and would need significant input.

[cbarrete]

I fully agree with all of those points, and would like to add that a structured approach like https://diataxis.fr/ might be helpful. There have been a few times when I wanted to improve the upstream docs and just wrote them internally instead because there was no good place upstream to put them, and I didn't have the bandwidth to revamp the whole structure of buck2.build/docs, especially since communication can be a bit slow at times. It's partially on me, but some effort spent on better structuring the docs would likely make it easier/more likely for users to contribute.

I'm also willing to spend some time writing documentation, but I also need some guidance as I cannot document things which I do not understand well (see https://github.com/facebook/buck2/issues/666 and https://github.com/facebook/buck2/issues/667 for example).