Chicago June Observations
At the Write/Speak/Code conference held in Chicago, IL, a team member attended the coding portion of the conference to observe attendees interacting with the Draft Web Design Standards. These attendees were participating in their very first open source project and were prime candidates to observe to understand user on-boarding.
Attendees of the conference were given the choice of open source project they would like to work on as their first project. Some broke up in pairs to work on similar tasks, others worked solo.
As the attendees began to work on the Draft Web Design Standards, we would walk around and listen any issues or concerns they had. If anything came up of note, e.g. issues setting up the project, the team would engage with probing questions to learn more about how the issue occurred and how the attendee was trying to resolve the issue.
Here are the top observations coming out of the research:
- It wasn't clear if they needed to recreate the site as a whole or just the draft design standards.
- Some attendees were starting off with a fresh install and ran into issue that were based on being unfamiliar with open source projects and node.
- Other attendees had development environments in place that weren't updated and kept getting errors that confused them.
- After awhile, a few attendees noticed that the website for the draft standards had additional instructions, but they stumbled onto that fact rather than being directed there from the repo.
- Given the level of experience with web development and open source projects, some of our terminology confused them. E.g. NPM
- The steps that need to be followed to set up the project locally confused some attendees since some instructions included multiple steps to follow.
- "I can't find all of the dependencies though?"
- "Do I fork it to my own personal repo?"
- Multiple files with the same name can show up when doing a search. E.g. style.css
- "I'll try not to mess anything up..."
- It wasn't clear to attendees if they needed to download the whole repo to get started or just the files they were focused on.
- One suggestion that was heard was to write the instructions based on the goals of the contributor, which could help guide them during setup and contribution.
- For bug issues, contributors that are new to open source projects may need additional direction on how to replicate the bug so they can attempt to address it.
- Other steps in the instructions are referenced in earlier steps, but the headlines further down don't match the phrases used when it was referenced. E.g. Discussion NPM setup
- Attendees were observed using google to locate other forms of instructions because the instructions included in the repo didn't provide enough guidance.
- Clear instructions on how to contact to team to address any initial issues or questions
- Provide additional context around the Pull Request template to allow novice contributors to better create Pull Requests.
- "Should we download the whole repo?"
- Provide a dashboard that points to the current focus of the team to allow new contributors to get started.
- Contributors need some guidance on how to use filters to find issues that they can start to work on.
- Provide guidance on the types of development frameworks that are acceptable when creating contributions to the site or the draft standards.
- If an issue is centered around a visual problem, the issue should include annotations are included to help contributions understand what the real problem is.
- "Are things prioritized at all?"
- "How does assignments work? Can I assign something to myself?"
- "How do I get started?"