Weekly Team Meetings: Oct-Dec 2023

jupyter / docs-team-compass

Documentation Work Group Discussions

BSD 3-Clause "New" or "Revised" License

5 stars 3 forks source link

Weekly Team Meetings: Oct-Dec 2023 #3

Open ericsnekbytes opened 9 months ago

ericsnekbytes commented 9 months ago

Here is a record of the agenda/minutes for our weekly meeting. Everyone is welcome to join.

Navigation:

Next 6 months (Jan-Jun 2024) here

Let's avoid using this thread for discussion. If you'd like to discuss something in the minutes, open a separate issue and reference this thread.

ericsnekbytes commented 9 months ago

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 (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

ericsnekbytes commented 8 months ago

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 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?

ericsnekbytes commented 8 months ago

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
  - 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

chbrandt commented 5 months ago

October 25, 2023

name	org	username
Eric Gentry	Anaconda	@ericsnekbytes
Carlos Brandt	CUB	@chbrandt

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

chbrandt commented 5 months ago

November 1, 2023

name	org	username
Eric Gentry	Anaconda	@ericsnekbytes

Agenda

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

chbrandt commented 5 months ago

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
- Started working on the History of Jupyter doc

chbrandt commented 5 months ago

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
  - PR 28, file get_involved.md
  - Repo with jupyter.org docs

chbrandt commented 5 months ago

November 29, 2023

name	org	username
Eric Gentry	Anaconda	@ericsnekbytes
Carlos Brandt	Constructor Uni	@chbrandt

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/

chbrandt commented 5 months ago

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

chbrandt commented 5 months ago

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
  - 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

chbrandt commented 5 months ago

December 20, 2023

name	org	username
Carlos
Mike
Nick

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.