owned this note
owned this note
Published
Linked with GitHub
# Summary
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](https://github.com/jupyter/docs-team-compass) for more information about the Docs Working Group
## May 15 2024
| name | org | username |
|------|-----|----------|
| Eric Gentry | Anaconda | @ericsnekbytes |
| | | |
### Agenda
- Carlos: will not be able to participate today.
---
## May 8 2024
| name | org | username |
|------|-----|----------|
| Eric Gentry | Anaconda | @ericsnekbytes |
| Carlos Brandt | | @chbrandt |
- No Agenda items
## May 1 2024
| name | org | username |
|------|-----|----------|
| Eric Gentry | Anaconda | @ericsnekbytes |
- No attendees
## April 17 2024
| name | org | username |
|------|-----|----------|
| Eric Gentry | Anaconda | @ericsnekbytes |
| Carlos Brandt | | @chbrandt |
### 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
| name | org | username |
|------|-----|----------|
| Eric Gentry | Anaconda | @ericsnekbytes |
### Agenda
- Add your item here!
## April 3 2024
| name | org | username |
|------|-----|----------|
| Carlos Brandt | | @chbrandt |
### Agenda
- Skipping this meeting, no items/attendees
## March 27 2024
| name | org | username |
|------|-----|----------|
| Eric Gentry | Anaconda | @ericsnekbytes |
### Agenda
- Skipping this meeting, no items/attendees
## March 20 2024
| name | org | username |
|------|-----|----------|
| Eric Gentry | Anaconda | @ericsnekbytes |
| Carlos Brandt | | @ chbrandt |
| Jason Weill | AWS | @JasonWeill |
| Rosio Reyes | Anaconda | @RRosio |
### 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
| name | org | username |
|------|-----|----------|
| Eric Gentry | Anaconda | @ericsnekbytes |
| Jason Weill | AWS | @JasonWeill |
| Carlos Brandt | | @chbrandt |
| Rosio Reyes | Anaconda | @RRosio |
### 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
| name | org | username |
|------|-----|----------|
| Eric Gentry | Anaconda | @ericsnekbytes |
### 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
| name | org | username |
|------|-----|----------|
| Carlos Brandt | | @chbrandt |
| Rosio Reyes | Anaconda | @RRosio |
### 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
| name | org | username |
|------|-----|----------|
| Carlos Brandt | | @chbrandt |
| Eric Gentry | Anaconda | @ericsnekbytes |
| | | |
### 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
| name | org | username |
|------|-----|----------|
| Eric Gentry | Anaconda | @ericsnekbytes |
| Carlos Brandt || @chbrandt |
### Agenda
- Discussed some subproject 'documentation' issues
- Personas [Jupyter #683](https://github.com/jupyter/jupyter/issues/683)
- Diagram standardization [Jupyter #667](https://github.com/jupyter/jupyter/issues/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](https://docs.jupyter.org/en/latest/)? 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
| name | org | username | your Jupyter "Aha" moment |
|------|-----|----------|----|
| Carlos Brandt | | @chbrandt | |
| Eric Gentry | | | |
| Ana Ruvalcaba | Cal Poly University | @Ruv7 | |
| Jeremy Tuloup | QuantStack | @jtpio | |
| | | | |
### 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
| name | org | username | your Jupyter "Aha" moment |
|------|-----|----------|----|
| Carlos Brandt | | @chbrandt | |
| Eric Gentry | | | |
| Jeremy Tuloup | QuantStack | @jtpio | |
| | | | |
### 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
| name | org | username | your Jupyter "Aha" moment |
|------|-----|----------|----|
| Eric Gentry | Anaconda | @ericsnekbytes | |
| Carlos Brandt | | @chbrandt ||
| Rosio Reyes | Anaconda | @RRosio ||
### 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](https://github.com/jupyter/docs-team-compass/issues/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
| name | org | username |
|------|-----|----------|
| Eric Gentry | Anaconda | @ericsnekbytes |
||||
### Agenda
- ...
## December 20, 2023
| name | org | username |
|--------------------|------------------------|-----------|
| Carlos |||
| Mike |||
| Nick |||
||||
### Agenda
- On [issue #31](https://github.com/jupyter/docs-team-compass/issues/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](https://github.com/jupyter/docs-team-compass/issues/31#issuecomment-1864804761):
- 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
| name | org | username |
|--------------------|------------------------|-----------|
| Carlos Brandt | Constructor University | @chbrandt |
| Matthias Bussonnier| Quansight | @carreau |
| Eric Gentry | Anaconda | @ericsnekbytes |
| Rosio Reyes | Anaconda | @RRosio |
| | | |
||||
### Agenda
- Eric G
- Jupyter Executive Council (EC) acceptance!
- [Issue here](https://github.com/jupyter-governance/ec-team-compass/issues/19)
- 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](https://jupyterlab.readthedocs.io):
> A computational notebook is a shareable document that combines computer code ...
This text is copy-and-pasted from [Jupyter Notebook](https://docs.jupyter.org/en/latest/#what-is-a-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
| name | org | username |
|------|-----|----------|
| Eric Gentry | Anaconda | @ericsnekbytes |
| Carlos Brandt | Constructor University | @chbrandt |
| Rosio Reyes | Anaconda | @RRosio |
||||
### 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
| name | org | username |
|------|-----|----------|
| Eric Gentry | Anaconda | @ericsnekbytes |
| Carlos Brandt | Constructor Uni | @chbrandt |
### Agenda
- Eric G
- Added a [PR for voting procedures](https://github.com/jupyter/docs-team-compass/pull/33)
- 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](https://github.com/jupyter/docs-team-compass/pull/32)
- 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!)
| name | org | username |
|------|-----|----------|
||||
- No meeting today (November 22)!
## November 15, 2023
| name | org | username |
|------|-----|----------|
| Eric Gentry | Anaconda | @ericsnekbytes |
| Carlos Brandt | Constructor University | @chbrandt |
| Rosio Reyes | Anaconda | @RRosio |
| | | |
### Agenda
- Carlos
- Review of [Jupyter "get involved" page](https://jupyter.org/community)
- [PR 28](https://github.com/jupyter/docs-team-compass/pull/28), file [`get_involved.md`](https://github.com/chbrandt/docs-team-compass/blob/get_involved/get_involved.md)
- [Repo with jupyter.org docs](https://github.com/jupyter/jupyter)
## November 8, 2023
| name | org | username |
|------|-----|----------|
| Eric Gentry | Anaconda | @ericsnekbytes |
| Carlos Brandt | Constructor University | @chbrandt |
| Rosio Reyes | Anaconda | @RRosio |
### Agenda
- Eric G
- Moots!
- Formalize a way/process for convening one of these
- Voting Criteria
- Founding members
- Carlos
- What is Jupyter start: [PR #23](https://github.com/jupyter/docs-team-compass/pull/23)
- Started working on the History of Jupyter doc
## November 1, 2023
| name | org | username |
|------|-----|----------|
| Eric Gentry | Anaconda | @ericsnekbytes |
### Agenda
- Time zone difference, probably everyone forgot ;)
- Eric G
- Moots!
- Voting Criteria
- Founding members
## October 25, 2023
| name | org | username |
|------|-----|----------|
| Eric Gentry | Anaconda | @ericsnekbytes |
| Carlos Brandt | CUB | @chbrandt |
||||
### Agenda
- Eric G
- Leftover time: [Dual Compatibility Guide](https://github.com/jupyterlab/jupyterlab/pull/14838) 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
| name | org | username |
|------|-----|----------|
| Eric Gentry | Anaconda | @ericsnekbytes |
| Carlos Brandt | CUB | @chbrandt |
| Mike | Quansight | @krassowski |
| Rosio Reyes | Anaconda | @RRosio |
### Agenda
- Carlos
- Define first tasks
- Issues 8 and 12 are related
- Eric G
- Charter split
- "Guide Book" [here](https://github.com/jupyter/docs-team-compass/blob/guide_book/guide_book.md)
- Go through "original discussions", see issue, and look for points to add to the guide book
- Repo rename to [docs-team-compass](https://github.com/jupyter/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
| name | org | username |
|------|-----|----------|
| Eric Gentry | Anaconda | @ericsnekbytes |
| Ana Ruvalcaba | Cal Poly State University | @Ruv7
| Carlos Brandt | Constructor University | @chbrandt |
| Mike | Quansight | @krassowski |
| Frederic Collonval | QuantStack | @fcollonval |
| Rosio Reyes | Anaconda | @RRosio |
### Agenda
- Eric G
- [Charter](https://github.com/jupyter/docs/pull/2) 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`](https://github.com/jupyter/jupyter) repository.
- Maybe rename `docs` to `docs-team-compass`/`documentation-team-compass`?
- Where should the docs live?
## October 4, 2023
| name | org | username |
|------|-----|----------|
| Eric Gentry | Anaconda | @ericsnekbytes |
| Frederic Collonval | QuantStack | @fcollonval |
| Carlos Brandt | CUB | @chbrandt |
| Mike Krassowski | Quansight | @krassowski
| Rosio Reyes | Anaconda | @RRosio |
### 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](https://www.libreoffice.org/download/download-libreoffice/) (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