Learn

Accessible Documentation

Mon, 01 Jan 0001 00:00:00 +0000

Covered in this guide#

What accessible documentation means
What work documentation authors have control over and responsibility for
Recommendations for accessible documentation structure, text, images, and videos
What areas documentation authors can advocate for or select for accessibility in others’ work
A checklist for quick documentation accessibility review
External resources related to these topics

Sources#

This guide was written based on

The Web Content Accessibility Guidelines (WCAG) principles
Accessibility user research with Space Telescope Science Institute and Project Jupyter
Documentation workshops in the Scientific Python project ecosystem
Experience doing accessibility work on open source projects.

It was written by Isabela Presedo-Floyd at Quansight Labs.

Choosing a project

Mon, 01 Jan 0001 00:00:00 +0000

Contributing to a Scientific Python project#

A common question from new contributors is: “how do I choose which project to contribute to”? Some people end up contributing to many different projects, while others tend to focus their effort on a single project. And while projects in the ecosystem have a lot in common, each has it’s own community—so there may be differences in culture, style, and decision-making processes. Ultimately, which projects you contribute to will depend a lot on your own personal interests and goals.

Community Manager Role

Mon, 01 Jan 0001 00:00:00 +0000

Who’s a community manager?#

A community manager for an Open Source scientific Python project is a dedicated and enthusiastic contributor who plays an important role in building and nurturing a thriving community. They act as a bridge between the project and its community members, creating an inclusive and collaborative environment. This person has a strong understanding of scientific Python and open source principles. They actively engage with community members, address their needs, offer support, and encourage their active participation. By organizing community events, facilitating discussions, and promoting knowledge-sharing, they ensure that the project’s community remains vibrant and connected. The community manager is passionate about Python programming and committed to promoting diversity and inclusion in the scientific open source software community.

Community Meetings

Mon, 01 Jan 0001 00:00:00 +0000

How to initiate a community meeting?#

Before starting the meeting, having a few items and discussion points in the agenda will help kick-start the meeting. These discussion points could be a mix of:
Issues or PRs from the GitHub repositories which need attention
Announcing any upcoming events/conferences to check if someone is going to attend them or is planning to
Important updates:
- These could be recent releases/new feature additions
- Addition/changes in the maintainer/contributor team
- Convergence of an ongoing discussion - a summary of how the community reached a decision
- Anything important which needs to be brought up before the community
- Let everyone know that the meeting is governed by a CoC

Ice-breakers#

Ice-breakers are usually effective when the participants are not familiar with each other
Apart from the general introduction, which is usually name and role, it’s effective to add a fun question (generally non-technical) to ask around; these are:
- Favourite song, movie, dish, sport, game, tourist spot etc.
- If you could teach the world one thing, what would it be?
- What’s one interesting fact about yourself?

How to address any critical issues in the project/community#

Sometimes, there are certain matter which needs to be brought up before the community for a more open and inclusive discussion
This helps in taking into account various perspectives from the community and choosing a solution which is in the best interest of the community

How to keep the conversation going?#

Occasionally, there are situations when the conversation during a community meeting dies, and it feels like you’re in a graveyard 🪦
- Having a set up of backup discussion points can help remove the awkward silence
- Going around in the audience to ask if they have something interesting to share with the community
  - What projects are they working on?
  - Something they learned which could be shared with the community
  - Asking around if the attendees need any help

How to conclude the meeting successfully#

The meeting should end on a positive note - if there has been any heated discussion/arguments, try to conclude before the end. And generally, in the end, you should:
- Conclude important points
- Revise tabled items - which were supposed to be discussed but didn’t get time
- Tell them about the next meeting

How to run office hours?#

Office hours are a great way to invite the community and answer their questions, guide them, help them understand any specific about your OSS project etc.
- Usually, the structure of office hours is open, but there are certain tips which could make it run smoother; they are:
- Greet and acknowledge every participant during the office hours
- Try to answer at least 1 question from everyone
- Maintain a document so that everyone can jot down their questions, so it’s easier to go through them
- Invite them to the community meetings for broader discussions

How to take meeting notes?#

Every community meeting should have some form of public record which can be stored as an archive - taking meeting notes is one way to do it. There are several ways to take notes efficiently, which is helpful for the community
- Record the essential things, decisions, and resolutions that were discussed during the meeting
- Writing cues during the meeting and then converting them into proper sentences is a helpful thing to do when you’re moderating/running the meeting
- Try to have a TL;DR section at the top - this would help the reader to decide if they want to dive into the full notes or not
- Example at: https://zarr.dev/community-calls/2023/2023-05-03.html

Some tips for your meetings#

Make time for demos/showcases/presentation
- The community members are always looking for exciting/innovative ways to use OSS projects in their workflow, and making time to showcase the work is a good element of a community meeting
  - The demos/showcases could be - how your project is used to solve a problem in a specific domain
Make time for newcomers
- New contributors or newcomers are the users who have the potential of becoming future maintainers and helping them in the initial phase is beneficial for both the project and the individual and is in the spirit of open-source
  - Having a dedicated time slot for the newcomers to help them
Make community meetings accessible to the broader community
- Take into account community members in different time zones, differently abled, unavailability etc.
- Take notes and upload them to the website
- Record the meeting

Meeting templates (TODO)#

NumPy Community Meeting template

Community Outreach

Mon, 01 Jan 0001 00:00:00 +0000

Use various social Media channels for outreach:

Twitter:
- Utilize hashtags relevant to the scientific Python community to increase visibility.
- Engage with users by responding to questions, sharing resources, and participating in discussions.
- Retweet and mention influential users and organizations to foster connections.
- Share updates on project releases, new features, and bug fixes.
- Highlight community contributions and achievements.
LinkedIn:
- Create a LinkedIn group for the project to facilitate networking and discussions among professionals.
- Share project updates, news, and job opportunities.
- Encourage community members to share their experiences and insights related to the project.
- Connect with other professionals and organizations in the scientific Python field.

Tools for community outreach(TODO)#

Speaking at Conferences and Events:#

Submit proposals to relevant conferences, emphasizing the project’s unique features and benefits.
Prepare engaging presentations that demonstrate the project’s capabilities and use cases.
Provide live demos or tutorials to showcase the project in action.
Connect with attendees during and after the event, answer their questions, and collect feedback.

Teaching Tutorials#

Organize regular online tutorials or sprints to educate the community about using the project.
Cover various skill levels, from beginners to advanced users.
Provide clear documentation and code examples.
Encourage community members to share their own tutorials and best practices.

Writing Blog Posts:#

Keep the community updated on important news, such as project milestones, partnerships, and funding.
Announce major releases, highlighting new features and improvements.
Share technical insights, tips, and tutorials related to the project.
Recognize and appreciate community contributors through dedicated blog posts.

Creating content#

Create video tutorials, screencasts, or live coding sessions to demonstrate the project’s usage.
Develop interactive Jupyter notebooks showcasing practical applications.
Produce podcasts or interviews with community members or domain experts.
Collaborate with other scientific Python projects for joint content creation, such as tutorials or blog posts.
Create illustrations on how your project works: https://github.com/zarr-developers/zarr-illustrations-falk-2022

Ecosystem

Mon, 01 Jan 0001 00:00:00 +0000

The Scientific Python ecosystem is a collection of open-source scientific software packages written in Python. It is a broad and ever-expanding set of algorithms and data structures that grew around NumPy, SciPy, and matplotlib.

First contribution

Mon, 01 Jan 0001 00:00:00 +0000

How to make your first contribution to open source?#

Before you start, make sure you have the following:

Getting started

Mon, 01 Jan 0001 00:00:00 +0000

Choosing a project to work on#

How do you choose which project to contribute to? There’s no single best way to choose a project, but here are some questions to think about when choosing:

Governance and Decision Making

Mon, 01 Jan 0001 00:00:00 +0000

How to interact with new community members

Mon, 01 Jan 0001 00:00:00 +0000

Warning

This is a draft document.

As a maintainer, you will be the first point of contact for new community members. It is important to embody a positive and helpful force for the health of your community.

Be welcoming#

Always behave in a manner that is polite, patient, and understanding. Many contributors are acting on their own time so try to create an environment that is energizing, not draining. Don’t forget that on public forums, potential new contributors will be monitoring the community dynamic before getting involved!

Install

Mon, 01 Jan 0001 00:00:00 +0000

Before installing Scientific Python libraries, you need to have Python itself installed. There are two, largely equivalent, ways of doing that, and we describe both below.

If you have a working version of Python on your system already (check by running python at the terminal), you can skip to “Segment 1: Set up a virtual environment”.

Segment 1: Python.org#

This is the official Python distribution, which uses the pip package manager. pip installs packages from Python Package Index, or PyPI for short.

Managing conflict

Mon, 01 Jan 0001 00:00:00 +0000

Warning

This is a draft document.

Code of Conduct#

It’s a good idea to have a Code of Conduct to hold your community members accountable to and create a safe and inclusive space for everyone. This helps establish clear expectations on how community members should behave respectfully in their interactions with each other and serves as a reference for fair arbitration when the need arises.

You can base your Code of Conduct off of similar projects’ ones or use the Contributor Covenant as a starting point, tailoring it to your community’s specific needs. Larger projects should have an impartial committee dedicated to handling Code of Conduct violations, and a method for community members to privately raise issues to them.

Meeting types

Mon, 01 Jan 0001 00:00:00 +0000

Warning

This is a draft document.

With growth and sustainability in mind, every OSS project would benefit from holding the following recurring meetings:

community
newcomers / open office
triage
documentation

Further meetings might be added depending on the current needs of the project. That said, one need not start doing everything at once - it might be chaotic.

Community Meeting#

A regular sync meeting for the project’s maintainers which is open to the community. Everyone is welcome to attend and contribute to conversations.

Next Steps

Mon, 01 Jan 0001 00:00:00 +0000

Scientific Python therefore requires having a firm grasp of Python itself. We suggest reading through the official tutorial, doing an online tutorial on exercism, or using any of the countless resources that exist online or in print.

Learning a new language can be challenging, but Python is fun—so keep trying and hang in there! The community is there to help you along the way.

So let’s cover some basics.

How to run your Python code#

Python is an interpreted language: that means that it reads a text file with instructions and executes those one by one.

Onboarding

Mon, 01 Jan 0001 00:00:00 +0000

Warning

This is a draft document.

Organizing sprints
- Organising sprints are an excellent way to invite new collaborators, solve issues, gather contributions and broaden the project community. Some helpful tips for organising a sprint efficiently:
  - Have a list of issues from the issue tracker that can be worked on. The issues should have a mix of code (bugs, features, fixes) and no-code (documentation) tasks so that they can accommodate a diverse set of participants
Handling a storm of new contributors during peak season (GSoC, Outreachy, GSOD etc.)

Project Management

Mon, 01 Jan 0001 00:00:00 +0000

Project management#

As a community manager, you might need to onboard contributors who may not contribute in technical ways.

Send a personalized welcome message expressing gratitude and introducing the project.
Provide an overview of the project’s mission, values, and community culture.
Highlight non-technical contribution opportunities like documentation, user support, translations, design, and community management.
Create clear contribution guidelines with step-by-step instructions and templates.
Maintain regular communication to share updates and opportunities.
Recognize and appreciate all contributions, both technical and non-technical.
Foster a welcoming and inclusive community environment.
Ensure adherence to the project’s code of conduct.

OSS management (TODO)#

Overview of issues and PRs among several repositories
- Reviewing PRs or assigning reviewers to the PRs
- Solving the issues/responding to the issues
  - Responding - to maintain communication with the author
- Closing stale PRs and old issues
- Labelling issues

Roadmap

Mon, 01 Jan 0001 00:00:00 +0000

Skills and Techniques

Mon, 01 Jan 0001 00:00:00 +0000

The OSS Management Skills Wheel describes 24 skills, divided into 4 core competencies, used by OSS community managers. It was initiated by Inessa Pawson and Sanket Verma during the 2023 Scientific Python Project Developer Summit (Seattle, WA).

Interpersonal

Engagement
Collaboration
Moderation, mediation, and intervention
Emotional integration
Train and teach
Mentoring
Cultural competence
Networking

Technical

Git and GitHub
Dev tools
PR and issues
Triage

OSS Management

Growth and sustainability
Governance
Meeting facilitation
Program design
Change management
Record keeping
Event planning
Recruiting

Communication

Ways to contribute

Mon, 01 Jan 0001 00:00:00 +0000

5 ways to contribute to Scientific Python without coding#

Scientific Python is code designed by scientists and engineers for science and engineering. All projects have a straightforward license that determines what you can and cannot do; typically, you may use and modify the software, as long as you give credit to the original authors. The entire ecosystem relies on peer review and community production, so your contribution is really important. There are many ways to contribute outside of coding—we’ll discuss a few.

Why contribute

Mon, 01 Jan 0001 00:00:00 +0000

Your time is the most valuable thing you have, so when taking part in volunteer activities it is always worth asking “why?”. Here are a few reasons:

Learn

Accessible Documentation

Covered in this guide#

Sources#

Choosing a project

Contributing to a Scientific Python project#

Community Manager Role

Who’s a community manager?#

Community Meetings

How to initiate a community meeting?#

Ice-breakers#

How to address any critical issues in the project/community#

How to keep the conversation going?#

How to conclude the meeting successfully#

How to run office hours?#

How to take meeting notes?#

Some tips for your meetings#

Meeting templates (TODO)#

Community Outreach

Outreaching to Social Media#

Tools for community outreach(TODO)#

Speaking at Conferences and Events:#

Teaching Tutorials#

Writing Blog Posts:#

Creating content#

Ecosystem

First contribution

How to make your first contribution to open source?#

Getting started

Choosing a project to work on#

Governance and Decision Making

How to interact with new community members

Be welcoming#

Install

Segment 1: Python.org#

Managing conflict

Code of Conduct#

Meeting types

Community Meeting#

Next Steps

How to run your Python code#

Onboarding

Project Management

Project management#

OSS management (TODO)#

Roadmap

Skills and Techniques

Ways to contribute

5 ways to contribute to Scientific Python without coding#

Why contribute