Anyone want to help with a round of documentation improvements?

[choldgraf]

This documentation has a lot of great content in it. It is also a little bit out-of-date in some places, and could be improved in others.

Since this documentation hasn't seen bursts of development in quite some time, I propose that we have a round of updates with the following goals:

• Streamline pages so that they're easier to discover
• Update links and content so that it reflects the current state of the ecosystem
• Describes more of the broader ecosystem, instead of just the notebook
• Updates the contributing documentation
• Potentially removing some sections that haven't had their content fleshed out

Is anybody else interested in working with me on this? I can try to dedicate time in the coming months to doing so. I'm happy to self-merge some things, but it'd be much better if somebody else could give some 👀 now and then.

I wonder if this is something that @GeorgianaElena might be interested in helping with?

[rogelj]

Hello @choldgraf - I would be happy to help, but I must say I would need some direction (not done this before...).

[GeorgianaElena]

Happy to help too ❤️

[choldgraf]

Sending a ping to @lheagy, who mentioned she may be interested in some docs improvements as well.

What I'd propose we do is to:

1. Each of us take a pass at the jupyter documentation and identify some things they think could be improved
2. Share those thoughts in this issue and come up with some actionable steps to improve things
3. Post that list in this issue and see if others in the community have thoughts
4. Start making some PRs for clearly-actionable things, or open issues to discuss more complex things

I'm happy to work with others that are interested in this, and I'll try to post a few areas of improvement myself soon. What do others think?

[parente]

There's work remaining in issue #430 to document:

1. How community members can contribute translations of the documentation
2. How CI/CD works for translations, from .po templates in the repo, to translations on Transifex, the deployments on RTD

Does that work fit with the spirit of this issue? It'd be great to work on both with others so that we have redundancy in understanding of the current translation process and can work to make it better.

[choldgraf]

Yes absolutely imo, it would be very helpful and hopefully can encourage more translation work in the future. Want to have a quick session where you explain the translation infra, and we can write down bullet points that can later be integrated into the docs?

[parente]

Want to have a quick session ...

That'd be great, @choldgraf. Do you want to start here or on a video chat later this week?

[choldgraf]

Either one works - if you have the time to write down your thoughts of how the process works, others would be able to see them too and we could use that as a first-pass at improving the docs around this. Then set up a video chat if there are extra discussion-points that arise?

[Kelechi-Olelewe]

Hey @choldgraf & jupyter community, I'd love to get involved if possible. I don't have much experience when it comes to documentation, but If I can contribute in any way I'd be willing to help. Should I still ping @lheagy?

[parente]

Either one works - if you have the time to write down your thoughts of how the process works, others would be able to see them too and we could use that as a first-pass at improving the docs around this.

I'll open a PR with a draft doc explaining how the current translation flow works, independent of the current doc site structure. Anyone who wants to get involved can participate in reviewing and suggesting changes to that doc. We can figure out how to fit it into the site as a whole once all the info is written down.

I'll commit to getting that draft pushed by the end of next week.

[choldgraf]

that sounds great, thanks @parente :-) and @Kelechi-Olelewe we'll try to keep conversations around improving the docs in this thread / repo so you can join in if you wish! No need to re-ping Lindsey, I think she got the notification!

[choldgraf]

Some thoughts from a quick look through the docs (I'll update this as I think of more stuff):

• Quickstart - page should provide more context for the different kinds of tools in the jupyter ecosystem, and note that "quickstart" means something different for each
  • Explain what "try.jupyter.org" is
  • "Install" should be more like "install jupyter interfaces" instead of being notebook-specific.
  • "Install" Fix the left TOC it's not showing up
  • "Kernels" move the kernels section to a subsection of "Install"
  • "Running" move this to a "getting started" section in the Jupyter Notebook docs, and link to that
  • "Migrating" move this somewhere else, maybe an "advanced" section in these docs? These docs probably aren't as necessary now but should be kept somewhere.
• "Architecture" - provide more information on the index page so users know where to go
  • "IPython/Jupyter Notebooks work" - combine with visual overview of projects at the top. On one page, show the architecture of each piece of Jupyter. Link out to other docs as much as possible.
• "Narratives" - for now, I think we should remove this section because it seems to be missing a lot of content. I like the idea of it, so we could open an issue to track adding more user-stories etc
• "IPython" - we could move this inside the IPython section of Architecture? or reference?
• "Using" - remove the "upgrading jupyter" page and instead link out to how to install and upgrade each of the jupyter tools that we discuss
  • Rework the "how do I decide which packages I need" to a section like "I want to..." and sub-sections covering different use-cases and their potential tools
• "Contributing" -
  • IPython development guide is doubled in the left TOC
  • Perhaps move the IPython development guide to the ipython repo?
  • Update JEP page with latest information
  • Move sub-pages of developer guide into subsections on the same page
  • Move contributing for the first time to a "get started contributing" page

[avats-dev]

Hey @parente @choldgraf , I would also like to contribute. I might need some guidance once in a while though. 😄

[gitjeff05]

I'd like to contribute. One area that I would suggest for improvement is consistency among terms and definitions. Jupyterlab and Jupyter both have a glossary, but neither is comprehensive.

Mainly, there seems to be some ambiguity among the terms. For example, terms "notebook web application", "web application", "web-based application", "notebook application" and "jupyter application" are all used throughout the documentation*.

Other terms have the same issue (e.g., "kernel", "IPython kernel", "notebook kernel", and "jupyter kernel").

Obviously, it depends on the context and I'm not suggesting that all these groups of terms are equal. However creating a concrete glossary and then going back through the documentation to ensure consistency would be worth while. I know I had a lot of trouble at first understanding the difference between a jupyter notebook, notebook server, front-end and the kernel.
This could probably be done hand in hand with the architecture documentation.

* I searched the the docs directories of this repository, notebook, jupyterlab, jupyter_client, jupyter_server.

[starlightknown]

hey I am new to open source and I have been using jupyter from long and I would like to contribute. please let me know if I can help in any way