Jupyter Docs Weekly Meeting Notes

Welcome! The Jupyter Documentation Working Group's discussion/meeting notes are here. Meetings are weekly on Wednesday at 8am PST and everyone is free to join and listen or participate. You can add an item to the agenda if you'd like, and the group will discuss it during the meeting.

• See the jupyter/docs-team-compass repo here for more information about the Docs Working Group

Mar 5 2025

Agenda

• Eric G:
  • Cannot attend

Jan 15 2025

No items

Dec 11 2024

Notes

• Discussed state of docs and needs with Priya :)
  • Developing personas can be a useful next step
• "What is Jupyter" refactor PR is here

Dec 4 2024

Nov 6 2024

Agenda

• https://web.archive.org/web/20191026150206/http://blog.fperez.org/2013/04/literate-computing-and-computational.html
• https://ieeexplore.ieee.org/document/9387490

Sep 25 2024

Agenda

• Eric G: cannot attend

Sep 11 2024

Agenda

Aug 28 2024

Agenda

• Carlos (will not be in meeting)
  • : can you change the title of this note? It says "Summary" (to me), maybe we should name it "Jupyter Docs Weekly Meeting/Notes" or something similar.
  • DONE!

Aug 21 2024

• Edits to "What is Jupyter" document discussed

Aug 14 2024

• No attendees

Jul 31 2024

• No attendees

Jul 24 2024

• No attendees

Jul 10 2024

Notes

• Eric discusses the "What is Jupyter?" document, feedback from the EC, and next steps
• Nick discussed the difficulty of serving multiple audiences and possible strategies for best communicating the content going forward
  • Also mentioned VERY compelling use cases for Jupyter, stories about what Jupyter can be used for, that are not well told or communicated
    • One example is using notebooks to execute robotics actions for telecom scenarios
    • Another, more broadly, is LabView equivalent software for interactively running and getting metrics for machinery in a Lab (like a robotics lab)
    • Another is journalists investigating water bill datasets for a municipality and finding pervasive inaccuracies in customer bills (finding insights for journalists)
    • Widgets in general are an important story/use-case
• Tangle provides an example of a reactive document https://worrydream.com/Tangle/

Jun 26 2024

• Notes
  • Nick discusses…
    • Style checking with Vale
      • This can be added to CI for automated vocab/term checking, spell checking, etc.
      • He has a draft version!
      • Docs WG could add this into Lab CI, maintain a vocab list, others could use
    • Pixi can be used for automated docs building, so people don't have to build docs themselves

Jun 19 2024

• No meeting

Jun 12 2024

Agenda

• Eric G
  • Mermaid diagram not rendering for the What is Jupyter PR
    • Current rendered output is here (find latest by expanding the Checks/All Checks Have Passed section at the bottom of the PR)

Jun 5 2024

• No items today

May 29 2024

Agenda

• Carlos: Not gonna make it today.
  • The following item was noted from last weeks' Jupyter-Lab meeting.

  • Jupyter projects release structure/calendar: inform the current versions.
    • In last week's Jupyter-Lab meeting (22/May), there was a question about the next release of Jupyter-Lab which spun-off a discussion about different releases (ER, LTS, Beeta, etc), and a quick observation about conformity across Jupyter projects. To the former point, an issue was linked – https://github.com/jupyterlab/frontends-team-compass/issues/239 –, and an example by Firefox communicating there current versions, https://whattrainisitnow.com/. It is of interest of this WG the communication aspect as done by Firefox, for instance, and the need for conformity across projects.

May 22 2024

Agenda

• Notes
  • Carlos notes that a blog-post-first approach for these new high level docs is a good workflow, it publicizes the doc, gets more eyes on the doc, allows feedback from users, etc.

May 15 2024

Agenda

• Carlos: will not be able to participate today.

May 8 2024

• No Agenda items

May 1 2024

• No attendees

April 17 2024

Agenda

• Add your item here!

Notes

• Carlos continues work on "What is Jupyter" doc
  • PR: https://github.com/jupyter/docs-team-compass/pull/43
  • Eric to draft some edits today
  • Pr against docs jup org
  • Do this as a blog post first? Can gather lots of feedback, comments
  • Blog post has a date, point in time
  • Have last updated date
• Nick discusses his work on tooling for docs quality
  • He made a conda pkg for vale, an open source style/grammar checker
    • https://vale.sh/
    • https://anaconda.org/conda-forge/vale
    • mamba install -c conda-forge vale vale-spelling-en vale-style-microsoft
  • What it can do:
    • google/MS style guides to run on our docs
    • openoffice spelling list
    • Open source, rather than closed/grammarly
    • We can define Jupyter specific styling, see this example for MS capitalization
      • https://github.com/redhat-documentation/vale-at-red-hat/blob/main/.vale/styles/RedHat/CaseSensitiveTerms.yml
  • Language server is packaged up
    • std way to give grammar checking in your notebook cells
    • server implements the defined spec
    • vale-ls wraps the value exe
      • jupyter-lsp puts the behind web socketrs API
      • We can integrate this into CI for quality checking code, AND inside juypter for users to check their markdown cells
      • Piece that talks to the server is inside Lab codebase

April 10 2024

Agenda

• Add your item here!

April 3 2024

Agenda

• Skipping this meeting, no items/attendees

March 27 2024

Agenda

• Skipping this meeting, no items/attendees

March 20 2024

Agenda

• Mentoring, onboarding,
• Docs priorities/ big items:
  • What is Jupyter?
  • What do I need to use Jupyter?
• Jupyter users' persona
  • teachers
  • data scientists
  • developers
  • researchers

March 13 2024

Agenda

• Eric G
  • Documentation site metrics tools are WIP

Notes

• Jason discusses collaborations with Jupyter DEI group
  • In their recent meetings, notes about having an event where senior devs can tell people how they can contribute to Jupyter and OS in general
  • https://www.freecodecamp.org/news/how-to-contribute-to-open-source-projects-beginners-guide/
  • We could also make a "zero to hero" guide

March 6 2024

Notes

• Carlos, Github pages issue aggregator, review PR/merge
• Duplicate issues
• @bollwyvl
  • Grammar checking is WIP in JupyterLab repo
  • In-app docs in Lab, some preliminary work done
  • Author tools for Jupyter users! Jupyter started as thesis-writing tool…let's support founding vision/principles
    • Version of lab with Latex, pandoc, etc for writing thesis!
    • How do you want to use Jupyter? Which usage quadrant are you standing in? Personas, and which tools are needed by which
  • lab and server ext that knows how to find built docs pkgs, can also build docs pkgs if the upstream publishes a docs datadump
  • dash, zeal (offline docs systems)…epub, PDF…Language server protocol integration
  • value of docs content is amplified by good authoring environment
  • ipython interactive demo on the docs site…
  • iconography to signpost to users that something is interactive

February 28, 2024

Agenda

• Eric G: Cannot attend
• Rosio: email address for mailing-list
• Carlos: GH-Pages HTML table of docs issues
  • https://chbrandt.github.io/docs-team-compass/workflows/documentation_issues/

February 21, 2024

Agenda

• Carlos
  • WG mailing list
    • https://github.com/jupyter/docs-team-compass/issues/35
  • Disable actions in forks?
    • Mike pointed out (and showed) that forks have actions disabled by default (so, problem solved).

Notes

• Mike Krassowski
  • docs.jupyter outdated
    • releasing ipython outdated
    • Clean up first
  • security page can be added after
• Carlos notes marimo.io is a new interesting notebook technology

February 14, 2024

Agenda

• Discussed some subproject 'documentation' issues
  • Personas Jupyter #683
  • Diagram standardization Jupyter #667
    • use editable formats for collaboration in the drawings of diagrams. Excalidraw is the proposed tool.
      • should we bound that with some standard? Considering the different projects and their workflows.
      • we could layout the problem, alternatives and suggest through a PoC with existing diagrams. For instance, layout the workflow improving the process.
• ^The items above are recommendations for developers to use, how do we want to do these kinds of standardization efforts? Could do work as described above, follow up on tickets with solutions, post our work to the meta docs? We need to do work toward restructuring the meta docs to make it a friendly and efficient place for devs to go for resources like this
• Update copyright on Jupyter.org?
• Think about how we can gather more contributors and grow the docs wg
• Interesting "docu-mentor" ML model for docs https://www.anyscale.com/blog/building-an-llm-powered-github-bot-to-improve-your-pull-requests

Additional Discussion

February 07, 2024

Agenda

• Eric G

  • Use the old Notebook meeting for "Office Hours" for maintainers + community members https://github.com/jupyterlab/team-compass/issues/237

• Carlos

  • PR for list of documentation issues https://github.com/jupyter/docs-team-compass/pull/36
  • https://github.com/jupyter/docs-team-compass/blob/main/workflows/documentation_issues.md

• Mike

  • GSoC documentation video generator?
  • https://github.com/jupyterlab/team-compass/wiki/GSoC-2024
  • https://github.com/jupyterlab/jupyterlab/issues/8776

• Ana

  • Proposal: to create documentation with best practices for hosting/leading meetings in Jupyter community. Collaboration with DEI standing committee (JDEI) and Community Building working group (JCB). Martha Cryan will reach out to connect.
  • Idea: I would encourage collaboration among the groups doing community work (DEI, Media Strategy, Community Building, Docs, etc)

Notes

January 31, 2024

Agenda

• Carlos

  • Here is the table of (some) subprojects documentation issues:
    • https://github.com/chbrandt/docs-team-compass/tree/main/workflows
    • https://github.com/chbrandt/docs-team-compass/blob/main/workflows/issues.md
    • (csv and md files available, linked in the README is the markdown table.)

    Notice the repository linked above is a fork of docs-team-compass

  • Last week we've discussed about a dedicated repository for those actions, but maybe it's just better keep things in one place (ie, docs-team-compass) and have a clear README to direct people.

• Eric G

  • Write proposal for Jupyter Office Hours
    • Jeremy: a prior issue with a similar idea, although the meetings never took place: https://github.com/jupyter/notebook-team-compass/issues/13
  • Still working on Dual Compatibility Document

Notes

• (by Jeremy) Office Hours: https://github.com/jupyter/notebook-team-compass/issues/13

January 17, 2024

Agenda

• Eric G

  • Charter acceptance: Hooray!
    • Bring your ideas! How do we best do our work, follow our mission?
      • Moots, RFC for content spanning multiple docs for instance? Meeting structure, other activities…it's all open to new ideas
  • Emphasize
    • We are helpers, everything we do relies on consensus
    • Collaborative to the bone (work with subprojects, solicit ideas from others and the community, etc)
    • We're a Jupyter-wide group…
      • We can try to blaze trails, for how to best do work on a project-wide level (work processes, materials, etc)
      • We will face unique challenges
      • Getting people to agree on content, etc. may be difficult at times
      • North star:
        • Envisioning our role: As each subproject succeeds, so does Jupyter…each subproject adds something important to different stakeholders, and contributes to the overall health and success of Jupyter. If we can approach subprojects from a place of advocating for their needs, we will have partners to help achieve our goals.
  • Tie up loose ends from early in the proposal process
    • Make issues for anything that isn't recorded yet
    • Make our (Docs WG) materials great, lead by example
    • Add any other needed documents (restrict standards-setting powers to council vote, other rules, guidance for new members and contributors, record some of these thoughts to illustrate how the group should operate, issue labels, etc.)

• Carlos

  • Prototype for documentation issues tracking
    • Discussed in 20/Dec, commented in issue 31
    • Periodically collect "documentation" issues from subprojects
    • https://github.com/chbrandt/jupyter-docs-test/blob/main/jupyter_docs_issues.csv
  • ToDo:
    • automate creation of "reference" issues linking to originals
    • create "docs-tracking" repository
    • refine automation to avoid duplication and update occasional (original issue) title changes
    • set permissions in "docs-tracking" repo issues to block comments in there (tracking issues are not meant to host discussions, their goal is just to work as an index)

January 10, 2024

Agenda

• …

December 20, 2023

Agenda

• On issue #31: what would be a good, practical way of aggregating documentation issues?

  • The main points of the discussion were collected in the respective thread, in comment by Mike:
    • having a custom repo to mirror documentation issues from sub-projects (using a github actions automation) allowing to use Project Boards and similar (for example copy-pasting the the tile only setting the body as a link to the original issue)
    • exploring what https://goodfirstissues.com/ or https://goodfirstissues.dev/ does
    • exploring an approach using graphql for querying issues like https://github.com/regro/cf-graph-countyfair
    • using https://octobox.io/
    • starting with https://github.com/search?q=label%3Adocumentation+owner%3Ajupyterlab+owner%3Ajupyter-server++owner%3Ajupyterhub+owner%3Ajupyter-widgets&type=issues&state=open&s=created&o=desc

• Carlos: to have community meeting every two months, we could use our half-hour time slot + the half-hour that will be freed from the merge of Notebook-Lab meetings.

Notes

December 13, 2023

Agenda

• Eric G
  • Jupyter Executive Council (EC) acceptance!
    • Issue here
    • Please come to the meeting Thurs 10AM PST
• Carlos
  • How to improve re-use use of documentation chunk across Jupyter docs so we avoid duplication?

    • For example: consider the block about computational notebooks in JupyterLab docs frontpage:

      A computational notebook is a shareable document that combines computer code …

      This text is copy-and-pasted from Jupyter Notebook docs.

      • Is there a way we could embed the whole block from Notebook to Lab's documentation?

    • The problem:

      • More work when updating such information if/when necessary
      • Hard to keep track of those duplicates (demands deep knowledge of the docs, likely to be in the heads of the core developers)
        • External contributors would have to update multiple instances of the same issue, with assistance of developers from multiple projects (in this case, Jupyter Lan and Notebook teams)

    • The benefits:

      • Simplifies the maintenance of the content by having one source (in the example: Jupyter Notebook docs)
        • Eventually, (depending on the solution) the new version will be propagated to the child pages (in this example, JupyterLab docs frontpage)

    • Solution requirements:

      • (External) contributors willing to fix/update the documentation, they must know where it is coming from.
        • One way is to make it clear in the final HTML (eg, whole block under a hyperlink, or a link next to it)
        • Another way: the source of information would be defined in the raw file

    • Side effects:

      • Complexity in the documentation building system

Notes

December 6, 2023

Agenda

• Eric G
  • Go to EC (Executive Council) for recognition, maybe in new year?

Notes

• Async place for DWG work, support, community engagement
  • not everyone is github savvy/software eng
  • zuloup (matrix?), discourse
• Docs event in January?
  • Keyboard and alt text events
  • what new features can we try/add for no-mouse?
  • Pre, meeting, post work
    • What are we interested in? Make PRs for areas to focus on
    • During, do PRs
    • After, review and get it in
• Get git out of the way (so ppl can contrib without having software eng knowledge)
  • Tools/practices with Isabella, look up their corpus
    • https://github.com/isabela-pf/a11y-events/tree/main/workshop-resources/alt-text
  • Expert makes a PR (this doc is missing install for beginners, or something), community can add suggestion for alt text, expert can build/review
• DWG is making doors for people

November 29, 2023

Agenda

• Eric G

  • Added a PR for voting procedures
  • Go to Software Steering Council for official recognition
    • First deliverables
      • Host Guide https://jupyterlab-team-compass–226.org.readthedocs.build/en/226/host_guide.html
      • Add admin info to Jupyter.org docs

• Carlos

  • Warm up conversation:
    • https://symposium.openforumeurope.org/
    • https://openforumeurope.org/
  • Added a PR on the history of jupyter
    • In the history of jupyter, I think would be nice to have small inputs from senior/experienced members of the project

Notes

• (carlos) Proposal by Eric:
  - in the extra time go in some channels (reddit, issues, forums) where issues regarding docs can be addressed and/or collected.
• (carlos) on accessiblity by Tony:
  • To make sure that docs are accessible
  • Include axe in CI
  • https://github.com/deathbeds/nbconvert-a11y
  • https://github.com/validator/validator/
  • https://github.com/dequelabs/axe-core
  • https://en.wikipedia.org/wiki/Web_accessibility
  • https://developer.mozilla.org/en-US/docs/Web/Accessibility
  • https://www.w3.org/WAI/
    • https://www.w3.org/WAI/fundamentals/accessibility-intro/

November 22, 2023 (No meeting today!)

• No meeting today (November 22)!

November 15, 2023

Agenda

• Carlos
  • Review of Jupyter "get involved" page
    • PR 28, file get_involved.md
    • Repo with jupyter.org docs

November 8, 2023

Agenda

• Eric G

  • Moots!
    • Formalize a way/process for convening one of these
  • Voting Criteria
  • Founding members

• Carlos

  • What is Jupyter start: PR #23
  • Started working on the History of Jupyter doc

November 1, 2023

Agenda

• Time zone difference, probably everyone forgot ;)
• Eric G
  • Moots!
  • Voting Criteria
  • Founding members

October 25, 2023

Agenda

• Eric G
  • Leftover time: Dual Compatibility Guide work
    • Primary document
    • Secondary document
    • 6 example extensions
• Carlos
  • Started the compilation of docs of the subprojects
    • https://github.com/chbrandt/docs-team-compass/blob/main/subprojects_elements.md
    • listing documentations (rtd, sources)
    • listing repositories in orgs related to the projects (eg, example_extensions) for futre check against released docs
    • listing canonical distributions (eg from pypi)
    • dynamic relationships shown from project metadata
      • Some things are not gonna be obvious right away
        • Key design decisions that became principles
          • Why is Juptyer extensible? for example
            • from ipython days, was meant to make that interface extensible
            • magics are extensible, for instance
            • allow people ways to build their dissertation, was an early driver of extensibility
          • Can try to document these alongside history
          • "User always wins" for configs, design decision (users are not always in an environment they can control) is another example of a design principle that evolved

October 18, 2023

Agenda

• Carlos

  • Define first tasks
  • Issues 8 and 12 are related

• Eric G

  • Charter split
  • "Guide Book" here
    • Go through "original discussions", see issue, and look for points to add to the guide book
  • Repo rename to docs-team-compass
  • Characterize how documentation works in different subprojects (docs-in-code/docs on readthedocs, what automated systems are being used, etc.), make an issue
  • Diataxis, add to guide book
  • Merge Charter and Guide Book

October 11, 2023

Agenda

• Eric G
  • Charter draft
    • Establishes authority/voice in community
    • Doesn't need to establish everything in detail
    • Goal should be mostly static charter
    • Can take last section out of charter
    • Set strategy, find models for things we can reproduce
  • First targets (Make issues!):
    • What is Jupyter? Page(s)
      • History, what is ipython is good way to start
      • Fernando interview, what is Jupyter/history: https://www.theatlantic.com/science/archive/2018/04/the-scientific-paper-is-obsolete/556676/
      • List of official subprojects: https://jupyter.org/governance/list_of_subprojects.html
    • Ecosystem docs/how does this project fit inside Jupyter?
    • Docs structure consistency
    • Add CODE_OF_CONDUCT.md
    • Diataxis, best practices…four quadrant docs system
• Mike
  • docs repo vs jupyter repository.
    • Maybe rename docs to docs-team-compass/documentation-team-compass?
    • Where should the docs live?

October 4, 2023

Agenda

• Charter
  • https://github.com/jupyter/docs/pull/2
  • Communicate: Give a holistic view of "what is jupyter?"
    • Communication channels of this ecosystem
      • many disparate channels
      • connect the dots!
      • related to "get help" effort?
  • Bot for linking back to discourse on github
    • lab, frequently asked questions section
      • can populate from discourse / bot
      • embed links to readthedocs, faq section in the docs
      • script for adding links to hot topics/questions on discourse onto that page
      • need examples to help illustrate "not just docs"
      • put docs into lab application itself / link to readthedocs (put into charter/multiple delivery points)
        • make extension(s) for this
        • notebook + lab, deliver 100% of docs (through a specific package)… libre office does this, offline docs package (see link Help for offline use)
        • side note: https://github.com/jupyter/papyri is one technical approach which is being developed within Jupyter (not necessarily the approach the working group needs to take, for interface documentation we would probably want something on a different level)
          • but maybe we should possibly assist with integrtation of papyri (decisions to be made)
  • meta docs are an important area to focus on
    • modular architecture makes documentation difficult, to communicate concepts across projects
• Mission/Goals
• Volunteers for first work items