design

Note

Read this page carefully, and expect to return to it to ensure you're following our design process.

Hello designer! We're excited to have your help envisioning a new and improved Wordplay.

Design is about what we make and why. It's about serving our key stakeholder communities: secondary teachers and their students, especially multilingual students, English learners, students with disabilities, and neurodivergent learners. It spans every aspect of Wordplay's design, from it's visual design language and user interfaces, to the programming language and API designs, to the learning experiences and documentation. Design is not Figma — that is just a tool for doing user interface design, not a tool that is useful for all of the design that we do.

Here's the current flow of design work in this project that we expect you to follow:

Choose an issue

All issues are in this repository, on the issues page.

Our current top level design priorities are:

1. WCAG 2.2 compliance (to ensure Wordplay is accessible to everyone, regardless of abilities)
2. Support all of the world's natural languages (to ensure everyone can use Wordplay, regardless of language fluency)
3. Enable rich secondary-level teaching and learning experiences (grades 6-12) (to ensure everyone has opportunities to learn computing through school)

Wordplay's issues reflect smaller parts of achieving these larger design goals. All of the issues tagged needs design are ones that need design work. (There may also be some missing that tag, but also in need of design work. Some are tagged enhancement, which means they are new features that could be added to Wordplay. Others are tagged defect, which means there's something broken that needs a redesign. Issues that are in the 1.0 backlog are the highest priority.

Of course, there many design opportunities in Wordplay that aren't yet issues. If you have an idea for a new feature or an improvement, create a new issue, and we'll review it to see if we should include it. We need your voice on the design to make it better!

One you've chosen a needs design issue that you'd like to be responsible for (or created one yourself), note who else is assigned and communicate with them, asking to join the team if they are looking for helpers. If you're not also acting as the issue's developer, you may want to find a developer to collaborate with, so you can design around engineering constraints. When you're ready to request to join, tag a maintainer, explaining that you'd like to work on it, so everyone knows why you're assigned; they will assign you, or have a discussion with you about whether it's a good fit for your skills and goals.

Important

Some issues are tagged needs research. These are issues that may require 6+ months of full time research to successfully resolve, and may have no solution. They are best left to undergraduate research assistants, doctoral students, postdocs, and other researchers, who can invest a significant amount of time of reading, invention, study, and scholarship.

Research the problem

Find the other people who've contributed to it, or even the person who suggested it, and start doing research. What problem is it addressing? Should the problem scope be larger, smaller? Who's needs would it address? Capture all of this in the main body of the issue (not a comment), and revise it as you learn, so there's clear documentation about the need. Make sure you understand how any existing Wordplay functionality works in depth before you redesign anything. Do not assume that the research done on the issue is right or complete; it's your job to fully understand the nature of the problem before proposing designs.

One reasonable part of research is engaging with stakeholders (e.g., youth, teachers). If you want to do this (and for most design issues, you should), do not go rogue: consult with the leadership team about how. Talking to youth requires careful planning, talking to teachers requires careful consideration of their limited time, and talking to partners such as not-for-profit organizations requires long-term planning of professional communication and engagement. Do not take any of these kinds of outreach lightly; even a single poor interaction with a person, community, or organization and permanently harm our ability to learn with communities. That's why we manage these relationships centrally.

If you are unable to talk to stakeholders directly, study other existing research on the topic, learn from online communities that discuss the issue, and consult with the leadership team for suggested resources. There's a lot of knowledge in the world that can be gained about a problem. (If you're an Informatics student, INFO 300 Research Methods is the best preparation for this work.)

Propose designs

As you research need, you're going to generate concrete ideas. Your job is to envision concrete designs or redesigns that address the problem, and capture them in the GitHub issue's main body text (not in comments).

Which tools to use to do design depend on what you are designing. Some designs might be programming language features; you might only need text code examples to sketch designs in that case. Some might be user interface designs; for that you might use Figma. Other designs might be writing; for that you can just write text in GitHub. In general, choose the tool that best enables you to express your vision.

All designs should be embedded the GitHub issue you're designing for. If you need to include an image, include an image description, so contributors who rely on descriptions of visuals can understand what you're proposing.

Important

Do not link to PDFs. PDFs are not accessible to people who use screen readers without significant effort, and so anyone trying to read your design with a screen reader will not be able to. Do not link to external web links, as links bit rot and have permissions barriers. Everything must be embedded as accessible text and images in the main body of the issue.

Important

Do not link to Fimga designs unless also including screenshots from GitHub. It's okay to create interface designs in Figma, and include them as images with alt text, but we do not want external links in issues, as permissions change, designs get deleted. We need a self-contained archive of the proposal in an issue.

Important

Do not link to Google Docs. All text and content should be in GitHub issues, so everyone has full context for the discussion and proposals. The communicate can't count on random Google Docs linked to your personal accounts to being available in the future, but we can count on GitHub comments being available.

When you have a design sketch, consult with developers (including Amy) on the feasibility of the design. They may have perspectives on what is and isn't possible, or questions that your sketch does not yet answer.

Iterate

When you have a design ready for review, tag Amy or other design leads for design review.

Expect our design review to go as follows:

• We'll check to ensure the design specification in the main issue body, not in a comment, and ask you to move it there if it's out of place.
• We'll read the design specification and generate a list of ambiguities, inconsistencies within the existing design, and violations of the project's core design goals, writing a comment to describe them.
• You'll iteratively address design issues until the list is empty 🙂

Once there are no more concerns, we will remove needs design and add the tag buildable, which signals to developers that it's ready for engineering.

Build

See if you can recruit someone to collaborate on it with, and if you succeed, collaborate with them to ensure that it meets your vision. This should be a collaborative process, not something that you toss over to engineering; regular communication and testing is key, as you may need to revise your design as constraints and feasibility become more visible. A successful design project will ship the feature, and end with a high five between designers and developers.

Your job is done when either 1) you and a developer have submitted a pull request that is successfully merged into the main branch, or 2) you can't find a developer to work on it yet.

Repeat

Once you're done, move onto another issue!