Documentation structure

[jasongrout]

I think this article has some really good points about documentation structure, and the differences between tutorials, how-tos, reference, and explanations: https://www.divio.com/blog/documentation/

Here is an example of it in practice: https://brachiograph.readthedocs.io/en/latest/#contents

[trallard]

I was planning to do some work for #13049 - including adding documentation on how to use Gitpod for JupyterLab development.
Though, I struggled to find the right place to add this section within the current documentation structure. And eventually landed in this issue.

Observations

• Some sections are now a mixture of user guides/how-to's and reference guides (the most notable one is the Contributing section)
• Some subsections are pretty large and mix several (loosely related) content pieces, which can make it quite tricky for folks to find the information they need
• I have looked at all the sections and subsections, and overall it is possible to restructure to a diataxis (-like, meaning it will not be perfectly aligned to the framework i.e. the docs do not have tutorials, well only one actually) structure
• note: I am proposing only a restructuring here not a whole rewrite (the latter would be a bit of a nightmare and an absolute whole lot of work)
• I spent a good amount of time looking at how other projects have adopted the diataxis framework to get inspiration and a sense of how to break sections and content (e.g. NumPy, Gastby. Django among others)
• I tried my best to categorise and restructure the sections and sub-sections, this might not be perfect as is, but we can tweak stuff

So without further ado, here is my proposal

1. Navbar (based on the latest version that uses the PyData Sphinx theme sections Get Started, User Guide, Contributing, Developing extensions maybe Need help??
2. Bulk of the documentation structure:

• Get Started
  • What is JupyterLab? (currently Get started)
  • Installation
  • JupyterLab quick start (now Starting JupyterLab)
  • The JupyterLab interface
  • The command palette (currently Commands)
  • Using JupyterLab extensions
• User Guide
  • How to's
    • Working with files
    • Using the text editor
    • Working with notebooks
    • Using the code console
    • Using the terminal
    • Managing kernels and terminals
    • Using a specific kernel (currently Documents and kernels)
    • Working with multiple file types and output formats (not sure about this title - but now is File and Output Formats)
    • Using the debugger
    • Using the table of contents
    • Managing JupyterLab extensions (currently Extensions)
    • Exporting notebooks to other formats
  • Advanced user guides (separating these sections to make them easier to find)
    • Interface customization
    • JupyterLab Build Process
    • LabConfig Directories
  • Reference guides
    • Changing the display language (currently Localization and language)
    • JupyterLab on JupyterHub
    • Real Time Collaboration
    • JupyterLab Application Directory (currently Advanced Usage)
    • JupyterLab User Settings Directory (currently under Advanced Usage)
    • JupyterLab Workspaces Directory (currently Advanced Usage)
    • JupyterLab URLs
    • JupyterLab high level architecture (currently in Contribute)
    • JupyterLab development
      • General codebase orientation
      • Using JupyterLab components
      • Design patterns
      • CSS patterns
      • Performance tips
      • JupyterLab API reference
    • JupyterLab extensions development
      • Common extension points
      • Reusing JupyterLab UI
      • Document widget extensions
      • The notebook plugin
      • Using React
      • User interface helpers
      • Extensions internationalization and Localization
      • Extension migration guide
      • Tutorial: Making a JupyterLab extension from scratch
  • Extras
    • Troubleshooting
    • FAQs
    • JupyterLab Changelog
• Development or Contributing (I prefer the latter)
  • Introduction - general guidelines
  • Contribution workflow - summary (TLD;R) - (📝 new section see NumPy's doc for inspiration)
  • Where to start
    • GitHub issues and labels (currently Labels used by triagers, tagging issues with labels, issue management, definition of ready)
  • Contribution workflow - detailed section
    • Contribution guidelines
    • Git/repo specifics (forking, cloning, etc.) (see NumPy's section for inspiration)
    • Setting and using your Development environment
      • Local dev environment
        • Building JupyterLab(currently Installing JupyterLab)
        • Running JupyterLab in development mode (currently Run JupyterLab)
        • Running the tests
      • Remote dev environment with Gitpod (📝 new see NumPy's section)
      • Other browser-based workflows
    • Development workflow
      • Basic workflow (from branching to submitting and updating PR)
      • Additional things you might want to do (or another title)
        • Performance Tests
        • Visual Regression and UI Tests
        • Contributing to the debugger front-end
        • Tips and tricks for debugging (consolidate Inspecting debug messages in VSCode, Debugging in the Browser and miscellaneous bits in Build and run the testsDebugging in the Browser)
        • Build and run the stand-alone examples
        • Building the NPM packages
        • Testing changes to external packages
        • JupyterLab build utilities
        • Notes - these could be added to the relevant section instead of being a stand-alone bit
    • Contributing to the JupyterLab documentation (restructuring docs related content)
      • Building the JupyterLab documentation (currently Writing Documentation)
      • Writing style guidelines
      • User Interface naming conventions
      • Screenshots and animations
      • Keyboard shortcuts
    • Other ways to contribute to JupyterLab
      • [Reporting a security vulnerability](currently a small sentence in Contribute)
      • Reporting an issue
      • Internationalization and localization(the contribution workflow should be here ideally)

I am only proposing two new sections here:

1. The Gitpod docs (marked with 📝)
2. A TLD;R contribution workflow (marked with 📝)

The rest of the content is all present in the current documentation.
Overall I think this proposed structure will make the docs easier to navigate and thus improve their usability.
Also, it would help contributors like me that end up all confused when trying to add new content and cannot find an evident place to do so.

And lastly, I can help with the restructuring if needed, as I do think it would be a massive improvement for users, developers, and contributors.

[krassowski]

including adding documentation on how to use Gitpod for JupyterLab development

There is already is a section on Contributing from within the browser which mentions Gitpod. It also mentions jupyterlab-playground which may enable hot-swapping some jupyterlab plugins from browser once Lab 4 lands with Lumino 2 (thanks to jupyterlab/lumino#377) too.

I am not sure if we want to hide extensions development so deep as you are proposing (User guide → Reference guides → JupyterLab extensions development); currently they are a top-level item:

I would advocate for keeping them separate as it crucial for JupyterLab to have robust extension community and make it easy for everyone to find this section ;)

On a general note, I would agree that the current https://jupyterlab.readthedocs.io/en/latest/developer/contributing.html has grown substantially and I see why you propose to split a summary out of it; I am not against, but personally I like having the ability to use ctrl + f to find items on a single pager rather than look though multiple pages. I guess there is merit in not overwhelming potential contributor too.

I would say that the "extras" like changelog and troubleshooting would be better placed at least one level higher (because when users are angry that something broke or something changed in a new release they want to find these sections quick or will get angrier).

One thing that I love in numpy's (and pandas) docs is this welcome screen:

[trallard]

There is already is a section on Contributing from within the browser which mentions Gitpod. It also mentions jupyterlab-playground which may enable hot-swapping some jupyterlab plugins from browser once Lab 4 lands with Lumino 2 (thanks to jupyterlab/lumino#377) too.

yes, I did not count that as a complete sub-section since it is a bullet points list - and I am not sure folks can get up to speed with the content there. But could we turn that into a more extensive section on "alternative/lower friction" setups?

I am not sure if we want to hide extensions development so deep as you are proposing (User guide → Reference guides → JupyterLab extensions development); currently, they are a top-level item:

This is something I was not sure of - it feels a bit o, dd in either place, tbh. I agree that it is not 💯 Lab, but it is crucial for the ecosystem. As I said - this proposal might not be perfect, and some of you have more context on why some things are the way they are.

Another option is to keep the structure as is (Extensions dev into References) and keep the link in the navbar to ensure visibility/findability. WDYT?

I would say that the "extras" like changelog and troubleshooting would be better placed at least one level higher (because when users are angry that something broke or something changed in a new release they want to find these sections quick or will get angrier).

Do you mean at the same level as User guides? It could work - we could add a "Need help?" or similarly aimed section in the navbar.

One thing that I love in numpy's (and pandas) docs is this welcome screen:

I do like this too, and the Gastby one - we should add something like that. I left this out of the original suggestion as it is a significant "new" item and would depend on the outcome of this issue to get right.

[afshin]

@krassowski:

I like having the ability to use ctrl + f to find items on a single pager rather than look though multiple pages

One convention I've seen to address this while maintaining the structure is to add a link for a single-page version e.g., for downloading, CTRL-F, etc.

[krassowski]

Another option is to keep the structure as is (Extensions dev into References) and keep the link in the navbar to ensure visibility/findability. WDYT?

I think it would work ok.

I would say that the "extras" like changelog and troubleshooting would be better placed at least one level higher (because when users are angry that something broke or something changed in a new release they want to find these sections quick or will get angrier).

Do you mean at the same level as User guides? It could work - we could add a "Need help?" or similarly aimed section in the navbar.

Yes, that what I was suggesting. I would not personally search for changelog in "Need help?" but maybe it's a me thing. Looking at other projects, almost all I checked have "Release notes" section in the top level (pandas, numpy, matplotlib, scipy); sklearn does not (they have it under "more" which does not fully count).

[trallard]

Adding the changelog to the navbar helps.

@afshin @jasongrout I'd really like to help with this reorg. Would it make sense to pop by a JupyterLab community meeting and share/discuss this to move forward?

[jasongrout]

Would it make sense to pop by a JupyterLab community meeting and share/discuss this to move forward?

Yes, that would get a lot of eyes on it. Thanks!

[jtpio]

Would it make sense to pop by a JupyterLab community meeting and share/discuss this to move forward?

Even a draft PR to get this started would be great, thanks!

[trallard]

Sounds good - I have had scheduling conflicts the past couple of weeks so have been unable to make it to the JLab calls