Write an opinionated onboarding guide and identify onboarding papercuts to resolve

[chrisjrn]

The onboarding tutorial is cumbersome and includes a lot of jumping-off points into more complicated sections of the docs.

The task here is:

• Create an onboarding documentation that builds up the contents of the example-python repo from first principles
• Make tickets for things that make the onboarding process cumbersome and complicated

[Eric-Arellano]

Create an onboarding documentation that builds up the contents of the example-python repo from first principles

Does this presuppose we want language-specific onboarding guides? A "Go onboarding" etc. I bias towards that, but we may want more discussion there.

[chrisjrn]

@Eric-Arellano eventually, maybe.

My goal is not to show "how to set this up for Python", it's to show the steps that ended up at the example-python repo being configured the way that it was. My bias here is for minimal complexity and overwhelmedness, and I am not sure what that looks like without the first version being out there.

That said, there is probably value in going through the process for other languages to identify papercuts.

[Eric-Arellano]

Sounds good. Similar to the discussion you and I had yesterday in a meeting, I believe it's valuable for our guides to be focused. For example, Go has no concept of source roots. So if you're just using Pants for Go, don't waste time mentioning it! We try to be too clever and general right now.

That does mean more maintenance burden for us because we have more permutations of the docs..which is where in-repo docs are helpful to DRY similar content.

[chrisjrn]

First pass lives at https://dash.readme.com/project/pants/v2.12-docs-update/docs/the-opinionated-getting-started-tutorial

Feel free to offer feedback here.

[stuhood]

Thanks for writing that up! A few thoughts:

1. Definitely agree with merging the "Prerequisites", "Installing Pants", and "Initial configuration" pages.
2. I'm not sure that we should make this page Python specific. The most recent edits to the 2.12 docs attempt to highlight that the final step in the installation process is to visit a language specific page (step 6), and I think that even more strongly emphasizing that might be helpful.
   • One way to do that might be have a table of the "required" backends for each language in your step 3 (so that folks don't need to leave the page), and suggest that they can enable more backends in the final steps, which are language specific.
3. Mentioning source roots is somewhat language specific (Go and shell don't need them, Python and JVM do): if we think that we can have a fairly high success rate on funneling people into the language specific pages (we would need to), then highlighting source roots there instead might make sense.
   • Ditto interpreter constraints and thirdparty setup / lockfiles.

[chrisjrn]

@stuhood I've given this a bit of thought, and I'm not sure it's really possible to make a simple, focused guide without calling out specifics for a single language. Part of my goal here was giving people a clear "end state" that they'd end up with. In this case, it's ending up with a working example-python repository.

If we're able to generate docs in the future, then it might be possible to maintain multiple permutations, but for now, I want to keep it focused on Python until it's easier to make more opinionated guides.

[siemato]

I'm currently in my onboarding process, discovering what Pants is about. As far as I am concerned, it is highly valuable to start with a python project, even when not targeting Python development on the long run. For me, it was the precursor to hacking around with Pants toolchains (currently playing around with hugo as a markdown to docs generator). It's fine to have a guide per-language, but I strongly suggest, not to work that into the default learning path for Pants.

[Eric-Arellano]

Thanks @siemato for sharing your experience! That's super helpful <3

it is highly valuable to start with a python project, even when not targeting Python development on the long run. For me, it was the precursor to hacking around with Pants toolchains

Interesting, I would not have made that connection.

--

I'm generally +1 for per-language guides. We want people to have something up-and-running as soon as possible, given how easy it is to lose interest. This means get rid of any noise.

But I agree per-language is not as feasible until we have proper DRY with our docs, e.g. Sphinx allowing us to insert the same text multiple times.

Or, maybe we with our new move to in-repo docs (still via Readme.com), we are less concerned about the duplication because we can at least grep for things?

[siemato]

As far as I am concerned, the biggest selling points for Pants over tools like Bazel, Buck, [...] is the integration into native toolchains, especially the ability to import packages using native toolchains. This makes it attractive for individuals and small teams. Individuals don't stay alone, small teams get bigger and Pants can grow with them. That's a result of great design decisions in the past - lessons learned from V1. And as we all know, the first time is a test, the rewrite is always the serious endeavour.

This is key to Pants' DNA.

But it also means, it targets people that never got into contact with the kind of concepts and workflows, Pants excels in. They know nothing, or little, about how to manage or lay out monorepos, how to bridge the gap between versioning and working in a trunk.

And most importantly, they know nothing about how Pants can assist in these workflows!

DRY wasn't as big of an issue as having to jump back and forth through different pages. I think, it's more important to have a path that runs like a golden thread through the onboarding process. Something that guides through the concepts, best practices and design of Pants and - more importantly - through the environment Pants is used in.

The docs need to talk about the intersection of monorepos, workflows and deployment, covering all aspects deeply enough to have a foundation to build on.