conversation starter for introductory docs

[paddymul]

This is an attempt at streamlining the README to be more salesy and get people who land here the info that they need more quickly. The exact wording and terms isn't the point and obviously needs refinement.

[welcome]

Thanks for submitting your first pull request! You are awesome! 🤗

If you haven't done so already, check out Jupyter's Code of Conduct. Also, please make sure you followed the pull request template, as this will help us review your contribution more quickly.

You can meet the other Jovyans by joining our Discourse forum. There is also a intro thread there where you can stop by and say Hi! 👋

Welcome to the Jupyter community! 🎉

[paddymul]

We want the proper user facing term that identifies which persona they are

[paddymul]

I think this is a good tight sentence. I like the screenshot early.

My thinking is, when I land on a repo for a piece of software, the software should sell the benefits first, then explain how to install. If a repo explains how to install before showing me what it does, my thought is "why do I want to go through the effort of downloading this thing , when I don't know how it helps me".

It is also worthwhile to disqualify users who will never be a match for a product early.

[paddymul]

This is separate work and probably requires a separate landing page... but could we setup a webpage that reads the browser user-agent and suggests/auto-starts the most relevant download. I think the benefit here is less distraction more than it is a user not knowing what OS they are on.

[paddymul]

Can Uninstall be punted to a troubleshooting section? Or possibly the installer (more work I know)

[paddymul]

Let's talk together to make each one of these personas a tighter more apt description.

Are there other personas that I don't know about yet?

[paddymul]

I can take a look at writing the auto-package-selection page. Where would you want to host it? Does the source for that page live in this repo?

[mbektas]

@paddymul thank you. overall, I like your ideas on improving this documentation. but it feels like considerable effort needs to be put from our end on this enhancement.

[paddymul]

@paddymul thank you. overall, I like your ideas on improving this documentation. but it feels like considerable effort needs to be put from our end on this enhancement.

How can I break this down into smaller chunks that we can release?

How about this:

1. Auto-selecting landing page as a PR.
   a. make the auto-select landing page
   b. change README and docs intro page to link to the autoselect landing page, with backup small icons for different OSes
2. Persona specific doc pages as a PR
   a. I will write the first version, primarily by pulling the relevant existing sections of docs to a persona specifc landing page
   b. I will need some collaboration for refinement - especially for how we describe the persona, there usecase, and how exactly jupyterlab desktop solves their problem
3. Rewrite the README/DOCS intro to lean on the persona specific docs pages as a PR
   a. Splitting this up into two stages should make it easier to get across the line.

I am eager to do the bulk of the work... But I will need collaboration sessions (maybe 2 30 minute sessions) to get the wording tight.

[mbektas]

@JasonWeill do you have any bandwidth to work with Paddy on these efforts to improve documentation?

[paddymul]

I am still willing and eager to work on this if the interest from Jupyterlab desktop is there.

What is the interest level in

1. Auto configuring download page?
2. first defining the relevant personas? I think they are
   a. inexperienced data scientist looking for the quickest way to start running jupyter
   b. experienced data scientist looking to use jupyterlab with custom environments
   c. sysadmin/IT who is less interested in data science but does need to know how to support a userbase who is requesting jupyterlab
   Are there other personas that I am missing?
3. Given agreement on 2 and willingness to add them to docs, I will write separate docs/readme sections for each persona (mostly pulling from existing)
4. Finally given the above rewrite README/docs with more streamlined flow that doesn't get lost in the weeds.

[JasonWeill]

@paddymul Thanks for the follow up! I can take a look at your README as soon as I can. Sorry for not getting back to you sooner.

It might be good to open additional issues for, for example, revising the download page and making additional changes to the docs, so that we can deliver changes incrementally over time, with smaller pull requests. Thanks again for your interest in improving JupyterLab Desktop.

[JasonWeill]

@paddymul The Jupyter web site (GitHub repo) might be a better place for product recommendations based on personas. Today, when you go to jupyter.org, you see a few products listed (Lab, Notebook, Hub, and Voilà) and links to either download them or learn more about them. JupyterLab Desktop isn't mentioned at all on jupyter.org, so users are less likely to discover it.

Open source projects like ours often avoid the "Who is it for?" question in favor of saying that we're for everyone. That said, I like the idea of differentiating between our products to help new users make a decision: do they want Jupyter Notebook, JupyterLab, JupyterLab Desktop, or something else?

If you look at corporate web sites, like AWS's (disclosure: my employer), they include case studies based on real-world customer deployments. It might be better to add some real-world cases of people using Jupyter to jupyter.org. To me, a project README should be primarily about answering the questions, "What is this?" and "How do I get started using this?"