Jupyterlab extension tutorial not written for novice

[vivian-rook]

Problem

The jupyterlab extension tutorial is not written for readers who are not already familiar with things. Sorry I say things because it is unclear what I need to learn to understand the document.

The document is mostly ok until about

jupyterlab/docs/source/extension/extension_tutorial.rst

Line 253 in 864754e

.. code-block:: typescript

The code that is added isn't described. There is a brief description about how ICommandPalette is required, but what is ICommandPalette? The document doesn't seem to describe what ICommandPalette is, if I need it for everything, or some things, what other things there may be that are like it.

JupyterFrontEndPlugin has attributes in it. In the code we can see "id", "description", "autostart", "requires", and "activate", though there is no mention of where they are documented, or where I can learn more about what they do.

How to build the code seems to be described, though we run into the same kinds of things when we get down to the next code block

jupyterlab/docs/source/extension/extension_tutorial.rst

Line 337 in 864754e

.. code-block:: typescript

import { Widget } from '@lumino/widgets';
Widget is used a lot, though what is a widget? Much like ICommandPalette, are there more things like it? Where does one find them? It is used throughout the code at this point, but little explanation is given as to what it is.

One can copy and paste, and get exactly what is defined, though it is difficult to learn how to modify the code one worked on to do something else. I'm not sure if the document needs more information about what is happening in each step, or if it needs a header describing what skills and knowledge are expected to understand the document. As it stands lacking either leaves the document inviting to someone who does not know what is needed, but frustratingly useless to apply.

Finally the tutorial does not include any mention of the schema directory. Which seems necessary in the examples
https://github.com/jupyterlab/extension-examples
at this point. Some description of what they are would also perhaps improve the tutorial.

Proposed Solution

Add documentation describing each part of the code so that a novice can understand what is happening
OR
Add a header describing the knowledge that is needed to understand the document.

[ericsnekbytes]

@vivian-rook Thank you for writing up this issue. The issues you describe here are also problems in other parts of the documentation, and have been repeatedly brought up as pieces of feedback from various parts of the Jupyter community. This tutorial document needs to be improved, and we should use your feedback more broadly as a guidepost for any future work to improve the documentation for Jupyter 👍

[jtpio]

FYI @vivian-rook the extension examples repo contains a hello-world example, which may be good alternative to the extension tutorial: https://github.com/jupyterlab/extension-examples/tree/main/hello-world

Just linking it here in case it could be useful to you, or if you think there could be things to be improved there too.

[vivian-rook]

Hello! Thank yinz for the responses.

I hadn't looked at the hello-world example, instead I head right for the toolbar-button example. Though having read through it now, it does give a nice line by line description of what is happening, and I'm going to see if I can make more sense of it, as the links to other examples seem to build on one another. At least the hello-world example is what I was hoping to find in the first half of the tutorial (descriptions of what each line of code means, and closing with links to next steps).

I'll see where I can get from there and if it makes sense to someone who doesn't know much (me). I suspect it would still be constructive to list the skills that are needed to be proficient in making jupyterlab extensions, from what I'm reading it looks like typescript knowledge is somewhat assumed in the hello-world and very assumed in the tutorial. This and any other skills that are needed to really build an extension would be useful to note near the top of the document.

[krassowski]

from what I'm reading it looks like typescript knowledge is somewhat assumed in the hello-world and very assumed in the tutorial

I would carefully state that many (most?) of the contributors and extension authors started without any TypeScript knowledge and picked it up along the way. On the other hand, TypeScript (as Python) has evolved over the years and got more features so maybe it is not as easy these days?

I think that the tutorial should provide links to explanations of non-obvious TypeScript features (such as namespace merging) but otherwise it should only assume a good understanding of a programming language rather than any specific language. I would say that the tutorial should assume the ability of the person reading it to search up/read up on things they do not know which are general programming concepts (such as inheritance, interfaces) but should offer links to concepts more specific to Jupyter ecosystem (such as the provider pattern, tokens, and plugins, what is a lumino Panel/Widget).

[vivian-rook]

I would carefully state that many (most?) of the contributors and extension authors started without any TypeScript knowledge and picked it up along the way. On the other hand, TypeScript (as Python) has evolved over the years and got more features so maybe it is not as easy these days?

Which is fantastic if that has been the case. Best to learn a skill in the domain that one is hoping to apply it. Though in order to do that the tutorial has to be written with the view of a novice in mind.

[ericsnekbytes]

To add another point of reference/comparison, the Godot tutorials (an open source game engine) do a great job of being accessible and inclusive even to newcomers with little or no background knowledge of the many fundamental math, programming and graphics skills a person will use while developing games (they provide extra explanation and context to help these people, examples below):

• The beginner and the advanced vector math documents give diagrams and explanations of basic coordinate system and vector math concepts

  • Foundational concepts are explained and diagrammed:
    
  • Callouts to external resources are provided when additional details would be beyond the scope of the document:
    

• The Matrices and Transformations document and the Using 3D Transforms document, which explain and diagram fundamental concepts around coordinate systems, rotations, with corresponding details about euler angles, matrices and quaternions

  • 

• The shaders document provides some explanations of fundamental concepts for people who are not experienced with writing shaders

This extra-friendly and welcoming approach would fit well with Project Jupyter, because we have a lot of smart users who are not web developers or software engineers. For those of us who are immersed in software or web development, it's easy to forget how complex the Jupyter tech stack is, and how hard it is to learn for someone who maybe only does a little python scripting for their lab work.