Getting Started layout

[phofl]

Context:

The getting started section is not good currently. It has tons of information that are completely irrelevant for someone who has heard the first time about Dask or just wants to run an example and play around a little bit. The information in there is mostly what I would expect from a 2nd step section.

It's pretty confusing where you should start looking if you are someone who has never done anything with Dask and seems very complex.

Proposal:

We create a dedicated getting started section for the most relevant use-cases (currently we have content for bags, dataframes and arrays). They take a user through:

• Installing -> running a short example -> looking at the Dashboard -> How can I scale out

Descriptions are short and on point without introducing internals or stuff that is very Dask specific. Just get them to the point where they can run something and look at it on the Dashboard

The stuff that we have currently in the getting started section will be trimmed down a little and advertised as further reading (or something similar, I am not married to any of those terms).

This is not meant to be merged, just a proposal for a layout that we can then fill with content

[github-actions]

Unit Test Results

See test report for an extended history of previous test failures. This is useful for diagnosing flaky tests.

     15 files  ±0       15 suites  ±0   3h 24m 38s ⏱️ +56s
 13 121 tests ±0   12 190 ✅ ±0     931 💤 ±0  0 ❌ ±0 
162 468 runs  ±0  142 440 ✅ +1  20 028 💤  - 1  0 ❌ ±0 

Results for commit c37c804. ± Comparison against base commit 7ace31f.

♻️ This comment has been updated with latest results.

[phofl]

cc @jrbourbeau @mrocklin for thoughts

[mrocklin]

In general I think what I'm seeing proposed here is breaking up getting started content into API-specific pages. That seems like a reasonable approach to me.

I'm seeing also that you're proposing keeping the "10 minutes to dask" content, alongside "getting started". This doesn't make sense to me. If you make content that's good then probably "10 minutes to dask" becomes superfluous and can be removed, which seems appropriate especially given your critique of it above.

[phofl]

@mrocklin and I chatted offline. We will nuke the 10 minutes to dask page and add some of the content back in in a follow up

We will move ahead with the structure proposed here

[mrocklin]

@phofl thinking about this a bit more, I think it's also possible that using tabs rather than links will be nicer. I think that this is especially true if each of the getting started sub-pages are relatively small/simple. In this case I could imagine a single tabbed section (rather than lots of linked tabbed sections like we have today) about basic usage.

There are reasons against this (the page gets more complex) but the main reasons for that I see are ...

1. People stay on the page (which is good, each link tends to result in non-trivial dropoff)
2. We can reuse latter generic sections, like scaleout, rather than repeating them on all of the subpages

Just a thought. I think that a lot of figuring out the right design will become more obvious once we (you) start writing)

[mrocklin]

We will nuke the 10 minutes to dask page and add some of the content back in in a follow up

👍

Also, just to reiterate, I don't think that we need to add back in all of the content. I think that some of that content, like the task visualization stuff, is probably unnecessary for this kind of page.

[phofl]

The disadvantage with the tabs is that we can't link to them directly as far as I know (so I can't sent someone to the array getting started guide), which is the main motivator for me to group this in different pages

[mrocklin]

That seems less important to me than avoiding the user having to navigate through a link (both are small effects though). My hope anyway is that the dataframe/arrays/futures/whatever tabs would show up above the fold anyway, so a link to this page generally (and not the specific dataframe section) would work well.