Jupyter ecosystem docs updates #682
Conversation
| tools for computational notebooks and interactive computing. | ||
|
|
||
| ## Where do I start? | ||
|
|
There was a problem hiding this comment.
Maybe a "Who is this for section"
"Data scientist doing interactive analysis -> just start using jupyter with jupyter notebook"
"Existing Jupyter users who wants to build their first extension -> uhmmm... base guide to extending jupyter"
"want to contribute or file a bug against jupyter -> contributing guide".
Where to start is too broad a question to answer.
| - Jupyter Notebook offers a simplified, lightweight notebook authoring experience | ||
| - JupyterLab offers a feature-rich, tabbed multi-notebook editing environment | ||
| with additional tools like a customizable interface layout and system console |
There was a problem hiding this comment.
How about
- Jupyter Notebook offers the core Cell/Output non linear notebook environment.
- JupyterLab builds on top of the pure Notebook experience with a more IDE like environment that adds a file browser and multipel notebook tabsl
docs/source/index.md
Outdated
| ## Start Here | ||
| ## What is Jupyter? | ||
|
|
||
| The name "Jupyter" is an ambiguous, overloaded term that can mean several |
There was a problem hiding this comment.
Welcome to the Project Jupyter documentation site. Jupyter is the
umbrella project that covers many different software offerings and
tools, including the popular Notebook, Jupyter, and
JuyterLab web-based notebook authoring and editing applications.
This site acts as (meta) documentation for the entire Jupyter project.
The major subprojects from Jupyter are:
There was a problem hiding this comment.
My proposed wording states what Jiupyter is and makes it unambiguous.
I would order the major components as notebook, Jupyter, JupyterLab because that goes from simple to complex.
There was a problem hiding this comment.
Welcome to the Project Jupyter documentation site. Jupyter is the umbrella project that covers many different software offerings and tools, including the popular Notebook, Jupyter, and JuyterLab web-based notebook authoring and editing applications. This site acts as (meta) documentation for the entire Jupyter project.
The major subprojects from Jupyter are:
This is good. I think we can remove the second of those three items and make it Notebook and Lab (second item, Jupyter, is just the umbrella project). Will update.
There was a problem hiding this comment.
I think we need to address naming ambiguity somehow, because the current reality is that a lot of confusion stems from EXISTING multiple/ambiguous usages that is VERY, very widespread. Not sure the best way/place to acknowledge this so that people aren't caught off guard and then end up more confused...there's a deeper issue here about bad naming choices, but in the short term I'd like some kind of solution that addresses present realities but also takes a stance on the best language to use going forward...
There was a problem hiding this comment.
I agree we need to address the ambiguity... but not in the opening paragraph of this documentation. We want the initial statements to be coherent and forward looking, not cluttered with an apology for past ambiguity. Maybe as a point immediately after the coherent statements, under the title of explaining past ambiguity.
There was a problem hiding this comment.
What are the main pieces of ambiguity:
To my knowledge Jupyter refers to
- The Jupyter notebook
- The Jupyter project - with an executive council... The Jupyter project was responsible for putting on JupyterCon
- The command used to start
jupyter notebookorjupyter lab - The Jupyter of "Jupyter Widgets"
What else am I missing?
There was a problem hiding this comment.
Can you clarify, where that would be put? I'm trying to figure out what to do with that "What is Jupyter" section now that we have additional clarifications in the first paragraph (much of it can probably be eliminated now?).
|
@krassowski Fixed above mentioned issues, can you approve/merge this? |
|
@choldgraf Are you available to merge? |
Co-authored-by: Michał Krassowski <5832902+krassowski@users.noreply.github.com>
Co-authored-by: Michał Krassowski <5832902+krassowski@users.noreply.github.com>
Co-authored-by: Michał Krassowski <5832902+krassowski@users.noreply.github.com>
Co-authored-by: Michał Krassowski <5832902+krassowski@users.noreply.github.com>
This is part of a Jupyter-wide effort to better explain the Jupyter ecosystem to the community, by improving documentation for the Jupyter Project and its individual subprojects, and interlinking them.