Onboarding UX - Guerrilla usability tests

[kelenelee]

This study is focused only on DS onboarding, but findings may have implications for HfLA broadly.

• [x] I observed 1 volunteer onboard with the new onboarding issue template (created in #395). This was not a perfectly sterile usability test, but I was able to gain a lot of important insight into what Github looks like to someone new to it. Results and insights here.
• [x] P0? I interviewed another newcomer to DS who had submitted their first issue. It turns out that they had not attended an all-hands meeting or spoken with the PM – but they managed to follow the readme directions. It looks like there are going to be at least 2 personas – young people who are new to the workforce and concept/practice of documentation, and older career transitioners who are more familiar with Agile. so there was no actual observing
• [ ] P2
• [ ] P3
• [ ] P4
• [ ] P5

Recommendations

These are the simplest fixes:

• [x] Take newcomers to the onboarding issue template, straight from the repo homepage. The readme.md is not the normal place to write these kinds of directions, but the repo homepage is where the user got very lost. If users are visiting the repo homepage, but don't make it beyond to the wiki or the project board, then somewhere on the repo homepage there needs to be something really clear.
  • [x] @sandraberjan thoughts on the current state of the readme? It's not the prettiest writing, but I don't think it can afford to be any less vague

    If you completed Hack for LA onboarding, and spoke with our product manager Yasaman Roostaeian, your next step is to visit this page and click the green button Submit new issue.

• [ ] Add a description to our repo. Currently it says No description or website provided. It's at the top of the right sidebar, and could be an opportunity to add onboarding directions. But because it's a sidebar, it may not be as eyecatching as the readme. Neither I nor @allthatyazz have permission to edit this – can the stakeholder do it? What should our description say?
• [x] Remove onboarding information from our wiki/onboarding that's already covered by HfLA, reducing the amount of redundant info a newcomer has to read.

More complex proposals:

• [x] Move onboarding to a different project board
  • [x] Add link to create a new blank issue. Newcomers do not need to begin by looking for the project board, so the onboarding issue template now lives in the readme as well. And, instead of linking the issue template everywhere and increasing risk of broken links, the slack channel description will have a link to the readme instead
• [x] Create issue template for onboarding
  • [x] Delete unnecessary role-specific readings
  • [ ] change title to something more intuitive than onboarding since newcomers just finished onboarding with HfLA
• [x] Create offboarding issue template
• [x] Add PM onboarding tasks to onboarding template under role-specific tasks
• [ ] add "star" as a task. homepage has contributors, stars and it looks like there is nobody working here even though there definitely are
• [ ] add "pin" as a task
• [ ] profile about @ hackforla
• [ ] profile status?
• [x] Add a notice to our teams page so that people who find us via HfLA's team page won't be totally lost when our page is empty Use team @mentions (ex. @github/design for the entire team) in any comment, issue, or pull request.

More complex fixes will come as we observe more newcomers.

[kelenelee]

• https://github.com/hackforla/design-systems/issues/55 this issue could be interesting... seems like a more human way to onboard
• members should pin hackforla/design-systems to their profile
  • star
  • watch if they want more notifications

the following list has been reintegrated into #395

• wiki roster needs people's actual github handle
• homepage has contributors, stars and it looks like there is nobody working here even though there definitely are
• kanban board is full of issues that cannot be deleted. you can hide them from projects but that's not as intuitive as closing the issue – that feels like the issue should be out of sight out of mind.
• milestones are as close to real epics as we will ever get. editing them is painful, but you can link issues and at least you can close them. either epics are their own column and the children have the dependency label, or we switch to milestones. which prepares people better for agile? templates and copies create a lot of repetition and spam and makes it harder for future people to sift
• labels suck but they're so tempting, what is the value of size labels when we can't add them in stories?
• what was the point of velocity if it never ends? deleted that.
• if github is this painful to use then we will need a serious overhaul of how we use it, THEN a training video. no use training people to use garbage
• why are boards are sorted by age if that means the most important one is LAST
• calendly account is very useful for encouraging more 1-on-1s, which is crucial for relationship building
• learn to use backticks in markdown to increase legibility of things
• what is the purpose of the role labels? there's a distinction between a team is assigned this and the task is relevant to the discipline.
• the onboarding issue template now lives in the readme. instead of linking the issue template everywhere and increasing risk of broken links, the slack channel description will have a link to the readme instead. newcomers will be specifically asked to read the "readme" since it's not at the top of the repo page and I can't change the readability or layout of things.
• assignee, labels, settings icon doesn't show up at the beginning
• add more text to onboarding template to break down the steps even more and explain why this is happening

[sandraberjan]

@kelenelee The writing works: clarity is most important. I do not have any pressing changes. It is very clear.

[kelenelee]

It is very clear.

Thanks @sandraberjan for taking a look. I added some emojis to the headings in the readme to make them more eyecatching. What do you think? If the copy is good, then maybe the visual hierarchy can be played with.

The reason why I'm not 100% with this copy is that generally it's bad UX practice to have hyperlinked text say "click here" or "this page" but I can't think of a clearer way to say it. If I describe the content of the link, which is what the usual practice is for hyperlinks, then people might get more confused. The less info you have to worry about, the better right? I guess I wanted reassurance / gut check that breaking the rule of hyperlinked text is justified in this special case

I also added the project card which is found under our assets and branding drive folder – probably good to be compliant with HfLA practices :)

[allthatyazz]

After receiving feedback from new joiners who completed our team's onboarding issue, the issue template has been updated multiple times.

• Added the section "Learning about our Product and the history of the project" to provide new joiners with a clear understanding of the product and its background. This was identified as a key element missing from the onboarding checklist.
• Shortened the checklist to make it less overwhelming for new joiners. This was done to ensure that the checklist can be easily completed without taking up too much of the new joiners' time.
• Removed less relevant information and added more information about the products and processes. This was done to make sure that the checklist is relevant and up-to-date, and that new joiners can learn about the products and processes that are most important for their role.
• Eliminated the instruction on the Pin setup. Many new joiners expressed difficulty with this, so it was removed to make the onboarding process smoother and less frustrating for new joiners.