-
-
Notifications
You must be signed in to change notification settings - Fork 343
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
conversation starter for introductory docs #654
base: master
Are you sure you want to change the base?
Conversation
Thanks for submitting your first pull request! You are awesome! 🤗 |
|
||
If you have an existing JupyterLab Desktop installation, please uninstall it first by following the [uninstall instructions](user-guide.md#uninstalling-jupyterlab-desktop). | ||
## Who is it for? |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
We want the proper user facing term that identifies which persona they are
@@ -2,20 +2,18 @@ | |||
|
|||
JupyterLab Desktop is the cross-platform desktop application for [JupyterLab](https://github.com/jupyterlab/jupyterlab). It is the quickest and easiest way to get started with Jupyter notebooks on your personal computer, with the flexibility for advanced use cases. | |||
|
|||
![JupyterLab Desktop](media/jupyterlab-desktop.png) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
|
||
- [Debian, Ubuntu Linux Installer](https://github.com/jupyterlab/jupyterlab-desktop/releases/latest/download/JupyterLab-Setup-Debian.deb) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
|
||
If you have an existing JupyterLab Desktop installation, please uninstall it first by following the [uninstall instructions](user-guide.md#uninstalling-jupyterlab-desktop). |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Can Uninstall be punted to a troubleshooting section? Or possibly the installer (more work I know)
- [Windows Installer](https://github.com/jupyterlab/jupyterlab-desktop/releases/latest/download/JupyterLab-Setup-Windows.exe) | ||
- less technical users. Install Jupyter with one download and run it with a single click, no messing with environments and the command line. [Less technical user guide](./to-be-written) | ||
- Sysadmins/IT. Do you have to setup this jupyter thing for data scientists at your organization? [Sysadmin docs](./to-be-written) | ||
- Advanced users. Do you want a one-click way to manage your multiple jupyter lab servers running on your machine. Do you want to know about all of the advanced features and config [Advanced user guide](./to-be-written) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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?
|
||
Please check out the [Python Environment Customization Guide](user-guide.md#Customizing-the-Bundled-Python-Environment) if you plan to customize the Python environment to add new packages. | ||
[Click here to install Jupyterlab Desktop](./externally-hosted-page-to-be-written) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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?
@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:
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. |
@JasonWeill do you have any bandwidth to work with Paddy on these efforts to improve documentation? |
I am still willing and eager to work on this if the interest from Jupyterlab desktop is there. What is the interest level in
|
@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. |
@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?" |
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.