changed 4 years ago  
Linked with GitHub

Jupyter docs alt text

Test sprint on July 21, 2021

Welcome! Thank you for taking the time to help us test this sprint method and supporting accessible documentation.

Agenda

  • 15 minutes-25: Sprint goal and process walkthrough
  • 25–45: Work time!
  • 45–50: Review PR
  • 50–60: Participant feedback

How to particpate

  1. Report to the team what page of the docs you plan to work on.
  2. Write alt text for an image.
  3. Submit that alt text on this PR this PRvia a review comment suggestion. More suggestion support here. Note: If the image you want to add alt text to is not yet in the PR, tell Isabela and she can add it.
  4. Repeat steps 2 and 4 as much as you'd like. Be sure to coordinate with others to avoid writing conflicting alt text.
  5. Get review! Ask someone to review your alt text and make changes based on the feedback.
  6. Hooray! You did it!

JupyterLab docs

Alt text resources

Coordination:

  • Tony: interface.rst (from bottom)
  • Mars: interface.rst (from top)
  • Isabela: changelog.md

Participant feedback

(fill in at end of call)

  • Commenting doesn't work in browser private modes

  • (Mike) Should we work on a fork rather than on main repo? Every suggestion will trigger a notification for folks.

    • Do drafts do notifications or not? It's probably safer to do it on a fork.

  • Can we claim by making a comment on the line and then editing it later?

    • For actual event, breakout rooms per file?

  • (Mike) Click on the … on markdown file for rich display to see the image as you are writing it.

    • If you don't do this from the start, this will delete your comment.

  • (Mike) Some of the screenshots are outdated. Is there a place we can note that it needs to be updated? Or double checked.

    • Can this be helped by Galata?

  • Is is still helpful to write "bad" alt text? Yes.

  • Make sure there is one PR from the start. No confusion.

  • (Mike) Include in guide https://jupyterlab.readthedocs.io/en/stable/developer/contributing.html#user-interface-naming-conventions

  • We need punctuation in the guide

  • Batch commit suggestions?

    • For example, each breakout room could have someone as the 'suggestion approver' who had some training in (upcoming) JupyterLab alt-text style guide. That way, approval of suggestions happens in batches of 3 people, instead of the main room of 12 people
      • This also maintains one fork. For example, 12 people, 3 breakout rooms. Less chaos because less overlapping.

  • Commit messages? Should they be standard too?

  • Spell check?

  • Maybe in introduction, have primer on JupyterLab interface so that people know what a screenshot is showing, especially in cropped images

    • Ugly example
    • So non-technical people understand what this screenshot is.
    • Alt-text: "A screenshot of JupyterLab and it's files" -> "A screenshot of the left sidebar with a few files"

  • Is there an easy way to make sure we didn't miss any alt text items?

  • (Mike) Collaboratively review proposed alt text with

    Image Not Showing Possible Reasons
    • The image file may be corrupted
    • The server hosting the image is unavailable
    • The image path is incorrect
    • The image format is not supported
    Learn More →
    and
    Image Not Showing Possible Reasons
    • The image file may be corrupted
    • The server hosting the image is unavailable
    • The image path is incorrect
    • The image format is not supported
    Learn More →
    voting.

  • Need a break for future review

  • Copy editor at the end?

  • What do we need to do to wrap up the PR?

    • This time, Isabela reviewed and edited the PR post-accepted suggestions to ensure consistent style (kind of like a copy editor) and then made a clean PR to the main repo.
    • There wasn't much discussion around this PR, but since there is a goal to get this merged there could be other follow up work in this process depending on a specific project's review process.
Select a repo