organizing a low-code documentation sprint with y'all

[tonyfast]

hey pals.

some folks at quansight labs have been working on low-code documentation sprints that have been super successful. these events improve alt text in documentation, and adding to the accessibility of the documentation experience. we've successfully run these events for jupyter, numpy, and scikit-learn. so far the environment of these events is really fun and engaging.

i was wondering if y'all might be interested in teaming up for one or two meetings that introduce this format to your community, and maybe get some new names in the history.

here is a blog post about the event if you'd like to read more https://labs.quansight.org/blog/2021/09/low-code-contributions-through-GitHub/

[GenevieveBuckley]

I don't know if you've already been following the documentation refresh discussion, you can read that here: https://github.com/dask/community/issues/170

[GenevieveBuckley]

Also, from memory I'm not sure that the Dask docs have a ton of image. There are some images, but it's not image heavy the same way that say, napari is image heavy. So that might be a bit limiting?

[tonyfast]

thanks for the info @GenevieveBuckley i'll check out that thread.

if the documentation isn't image heavy then a focused effort is a good way to satisfy some critical requirements of the Web Content Accessibility Guidelines. it is worth while for us to improve the quality of the alt text for any disabled developers needing that support, especially foundational projects like dask.

[ian-r-rose]

Hi @tonyfast! Sorry to let this sit for so long. There was some discussion of this topic this morning at the Dask Community Meeting, and I think there is definitely interest in organizing such a sprint.

An accessibility-focused one would be pretty valuable, I think. For instance, there are ~70 images in the main Dask docs, most of which either have no alt or have not-particularly-useful ones. It's not a huge number, but they tend to be fairly technical, so I'm sure there's lots to be learned as well.

I'd be happy to be your main contact in wrangling Dask people (I think we could easily get ~5-10 people to either do the work or facilitate it by guiding, reviewing, etc). What do you think the next steps would be? Should we set up a meeting to talk further?

[GenevieveBuckley]

I can help out with things asynchronously too, provided it happens before the end of this year. So if that'd be helpful, let me know @ian-r-rose.

[ian-r-rose]

Thanks @GenevieveBuckley

[tonyfast]

@ian-r-rose @GenevieveBuckley thanks so much for offering to help

An accessibility-focused one would be pretty valuable, I think. For instance, there are ~70 images in the main dask docs, most of which either have no alt or have not-particularly-useful ones. It's not a huge number, but they tend to be fairly technical, so I'm sure there's lots to be learned as well.

oh this is a good number. that will provide an opportunity for y'all to run this format a few times to cover most of the images. you can read about how numpy is using this program https://hackmd.io/@marslee/BksnYfWVK we are still learning how to talk about technical content, i'll wrangle the different documents we have to prepare, in the meantime chartability is a place to start for guidance. part of the charm of the event is talking about how to write alt text for your project's specific images.

I'd be happy to be your main contact in wrangling Dask people (I think we could easily get ~5-10 people to either do the work or facilitate it by guiding, reviewing, etc). What do you think the next steps would be? Should we set up a meeting to talk further?

1. we meet, catch up, and do a dry run of the event so you know what to expect (im on pacific time now)
2. there will be a little bit of homework to prepare one or more pull requests against the docs.
3. choose an existing meeting to borrow for this event, or book a new event on your community calendar.
4. we'll facilitate a fun, hour long event that gets multiple people in dask's commit history.
5. we pat ourselves on the back because glue work is important
6. someone need to see the pull request through and merged.

alt tex kessions for diagrams charts and plots https://github.com/Quansight-Labs/jupyter-accessibility-workshops/blob/main/docs/alt-text-guide.md#diagrams-charts-plots

[ian-r-rose]

part of the charm of the event is talking about how to write alt text for your project's specific images.

I love this.

we meet, catch up, and do a dry run of the event so you know what to expect (im on pacific time now)

Cool, I'll reach out over email

[ian-r-rose]

Some notes from a meeting between myself, @tonyfast, @ncclementi, and @scharlottej13:

• We should organize a ~1hr sprint, preferably during an existing community meeting. During the last Dask Community Meeting, we discussed having some kind of set of demos or talks after regular updates. Could this be a good thing to schedule for that time slot?
• There is plenty of work to go around to do these kinds of sprints regularly. Initial work would probably focus on alt-text for poorly-annotated images and links. But after that there are lots of avenues for follow-ups, including:
  • HTML reprs in notebooks
  • Graphviz representations of task graphs
  • Upstreaming improvements to our sphinx themes
• A group of 5-10 people is good, many more than that can be difficult to manage (at least for our first meeting)
• We should follow up with @jsignell and @jacobtomlinson to make sure that an alt-text sprint would not conflict with their able work in https://github.com/dask/community/issues/170

If we are able to organize this for the 2021-12-02 Dask Community Meeting, we may also be able to get some of @GenevieveBuckley's time

[jsignell]

This is great! I don't forsee it conflicting with the docs refresh. We should just make sure that any outstanding docs PRs are merged before we start the sprint.

[ncclementi]

Leaving a note here to point out that we probably want to wait until we have the updated Figures in. See https://github.com/dask/community/issues/135

https://github.com/coiled/dask-community/issues/14 suggests the new figures will start going in very soon. Since Ian is involved in both efforts, I think he'll be able to keep an eye on that potential pitfall.

[tonyfast]

sorry for the delay in response. it seems that if dask has some new images/figures coming through the pipeline then they would be a great place to sprint on. y'all think we might be able to schedule an event some time in december?

i still owe some resources that i'll get to sharing this week, unless @isabela-pf has quick access to any resources for writing good alt text...

[isabela-pf]

@tonyfast I have some of my typical links if that helps!

• An alt text style guide proposed for Jupyter accessibility workshops that gives an overview on frequently asked questions (for transparency, I did help write this one). We've used this in some other projects too (like NumPy documentation). Most of the Jupyter-specific details can be ignored or replaced with other project-specific resources.
• My personal favorite resource, W3's Alt decision tree.
• WebAim's overview of alt text.
• Diagram Center's standards for alt text for graphs and charts, which is one of the only resources in alt text I've encountered that covers these types of images.

Hope that helps!

[ian-r-rose]

Thanks for the information @isabela-pf! We're working through the material over the next few days.

sorry for the delay in response. it seems that if dask has some new images/figures coming through the pipeline then they would be a great place to sprint on. y'all think we might be able to schedule an event some time in december?

We're trying to get the accessibility sprint going for a 1hr block during the Dask community meeting (calendar invitehere, along with a zoom link and a notes document) Thursday, December 2 (next week!). This meeting is held monthly, so there would be lots of room for follow-up sprints (perhaps every few months).

We're still working on getting the updated images into the docs, but I think we'll be able to get it done in time. Since you recommend working on a fork, there's also the possibility

A few questions for you @tonyfast and @isabela-pf:

1. Would you be able to make this time?
2. Does it seem realistic to do this so soon? If not, we can defer until later in the month. Planning is a bit complicated by the prevalence of holidays around this time of year.
3. If the answer to the above two are "yes", are you available to schedule a dry-run / planning meeting for Tu/W next week?

[tonyfast]

1. Would you be able to make this time?

yes, i am available to facilitate the event during y'alls meeting time.

2. Does it seem realistic to do this so soon? If not, we can defer until later in the month. Planning is a bit complicated by the prevalence of holidays around this time of year.

yes, we can make this work

3. If the answer to the above two are "yes", are you available to schedule a dry-run / planning meeting for Tu/W next week?

Tuesday would work best for me.

[scharlottej13]

Hi all! Just made the PR for this, feel free to let me know if we should make any changes!

[isabela-pf]

It looks good to me! Thank you so much for setting it up!