Skip to content
Please note that GitHub no longer supports Internet Explorer.

We recommend upgrading to the latest Microsoft Edge, Google Chrome, or Firefox.

Learn more
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Better onboarding for new contributors #70

Open
violasong opened this issue Jul 2, 2019 · 19 comments
Open

Better onboarding for new contributors #70

violasong opened this issue Jul 2, 2019 · 19 comments
Assignees
Labels

Comments

@violasong
Copy link
Member

@violasong violasong commented Jul 2, 2019

Update (December 31): Join me on Slack to follow along and help with the UX process!

Checklist: firefox-dev.tools

Checklist: Contributor Documentation

  • Refresh docs intro text
  • Refresh Getting Started text
  • Refresh Build page
  • Review other Firefox Contributor docs
  • Review docs feedback
  • Expand UI Review docs

Original description:

We need an initial lightweight solution for better onboarding docs/tutorials. (I'm thinking of this like an MVP - something that we can get done this month.)

What would this look like? Just changes to the introductory text on our docs or website? Or do we need to add an FAQs and troubleshooting page? Feedback needed from both those who mentor new contributors and contributors of any experience level :).

@violasong violasong self-assigned this Jul 2, 2019
@eduarmreyes

This comment has been minimized.

Copy link

@eduarmreyes eduarmreyes commented Jul 4, 2019

Lately, my attention gets better attracted when following these type of steps and seeing screenshots to compare my results versus what is expected. I understand it may vary depending on my development environment but I thought it was worth mentioning.

@fvsch

This comment has been minimized.

Copy link
Member

@fvsch fvsch commented Jul 4, 2019

I don't have a complete vision, just a few notes:

  • Entry point: firefox-dev.tools could be a better entry point for end users and contributors (dev & UX). Something a bit more like an inviting landing page and less like a markdown-to-HTML doc. And right now it's 100% developer-centric, the language and links there expect would-be contributors to be developers.

  • If we make a better entry point for contributors, how do we help contributors finding it in the first place? The Twitter account could link there, DevTools docs on MDN too, maybe other places? Maybe get a promotion spot in the Mozilla Developer Newsletter?

  • Show / Announce stuff more? There was some feedback on Slack about the DevTools project being a bit opaque for people trying to follow along on Slack and GitHub and other places. The Twitter account is good for that, with previews and requests for feedback; maybe those communications should be doubled on Discourse too?

  • A lot of open source projects have very public roadmaps and milestones; less so with DevTools. If you manage to hunt down DevTools-related meta bugs on Bugzilla you can get a picture of what is happening or going to happen, but I doubt many people who are not employees do that. Posts on https://hacks.mozilla.org/ are great but only report what is shipping, not what is cooking or plans for the future.

  • For UX contributors, the issues in this repo are probably a good tool, but sometimes we're not very reactive when people ask questions.

@violasong

This comment has been minimized.

Copy link
Member Author

@violasong violasong commented Jul 11, 2019

Thanks both for the ideas!

Lately, my attention gets better attracted when following these type of steps and seeing screenshots to compare my results versus what is expected. I understand it may vary depending on my development environment but I thought it was worth mentioning.

This sounds great - relatedly, I think @nchevobbe had some ideas for a interactive tool that would your analyze your build results? But maybe just adding more screenshots or sample results in the instructions would help.

firefox-dev.tools could be a better entry point for end users and contributors (dev & UX).

Totally agree! I think this is a great low-hanging place to start. Even adding an extra intro sentence would help a lot. And that's a really great point about the dev focus. A while back I had made a pull request to add a UX contributor link and need to poke that again.

If we make a better entry point for contributors, how do we help contributors finding it in the first place?

Posting it in those various places is a really good idea. The DevTools "Community" menu item could also link to it instead of to Discourse as it dows now.
image

Show / Announce stuff more? There was some feedback on Slack about the DevTools project being a bit opaque for people trying to follow along on Slack and GitHub and other places. The Twitter account is good for that, with previews and requests for feedback; maybe those communications should be doubled on Discourse too?

Discourse seems very low volume at the moment (at least for my purposes of trying to get feedback) so I have been planning to try other channels like /r/firefox.

A lot of open source projects have very public roadmaps and milestones; less so with DevTools. If you manage to hunt down DevTools-related meta bugs on Bugzilla you can get a picture of what is happening or going to happen, but I doubt many people who are not employees do that. Posts on https://hacks.mozilla.org/ are great but only report what is shipping, not what is cooking or plans for the future.

This is a really interesting point, though seems like it would be similarly complicated to sharing UX work, in terms of the dangers of making promises we don't end up fulfilling. Maybe @martinbalfanz and @digitarald have some thoughts on public roadmaps.

@violasong violasong added this to Backlog in Victoria's Tasks Jul 16, 2019
@violasong

This comment has been minimized.

Copy link
Member Author

@violasong violasong commented Jul 16, 2019

I think the easiest first steps to an MVP of this project are:

cc: @sole

Regarding non-dev contributions, this section from the debugger docs has some great stuff we can borrow

This comment from @fvsch has a great overview for newcomers.

The first step to get started is to check out the Firefox codebase. Firefox is using Mercurial, which is an alternative to Git. We have a "getting started" guide here: https://docs.firefox-dev.tools/getting-started/build.html

One bit of advice: you will only need "artifact builds", which are much faster than full builds, for this work. So when setting up, before building for the first time using the ./mach build command, I highly recommend following the steps in the Artifact Builds section.

The whole process is a bit long, you may need a few hours to get things right. If at any point you are stuck, you can ask for help on the Firefox DevTools slack at https://devtools-html-slack.herokuapp.com/

Once setup, most of the files you will need to change are in the devtools/client/locales/en-US directory. You can see its current content online here:
https://searchfox.org/mozilla-central/source/devtools/client/locales/en-US
You can use any code editor to edit them (VS Code, Sublime Text, any big IDE, etc.).

@violasong

This comment has been minimized.

Copy link
Member Author

@violasong violasong commented Jul 17, 2019

There could also be a landing page-like section on the homepage that shows a images of new features, at least for the following:
Grid Inspector
Fonts Editor
Shape Path Editor
Accessibility Inspector
Flexbox Inspector
Changes Panel
Inactive CSS

@nchevobbe

This comment has been minimized.

Copy link
Member

@nchevobbe nchevobbe commented Jul 17, 2019

When outreachy started, these were the main issues people struggled with:

  1. They had an issue building Firefox. The doc is not streamlined, so you have to open different pages to get to the content you want. This should be made easy.
  2. The doc references multiple ways of doing things (full build vs artifact builds, mercurial vs git, arc vs moz-phab, …). This is confusing for the new contributor (what should I chose), and it may reduce the help they can get from other contributors/mentors (I had people telling me they were using git cinnabar, or arc, and couldn't help them as well as I'd hope)
  3. People don't know well git/mercurial and end up "messing up" their repo. Which meant spending time on Slack asking them to print the result of some mercurial commands and telling them what command to run next. Extremely time consuming.

The ideas we should play with are:

  • Have only one document that people can follow to setup the work environment, only showing 1 given workflow (artifact builds + mercurial + moz-phab)
  • Have a "post-build" exercise where people need to complete some mercurial operations (there could be a text displayed at the end so people can check they did everything right). This could go like: create a bookmark to work on a bug, do a commit, amend the commit, split the commit into 2 commits, do another commit, move this last commit to another bookmark, …
  • Have an exercise to tell people how to use the browser toolbox/browser console
@janodvarko

This comment has been minimized.

Copy link
Member

@janodvarko janodvarko commented Jul 17, 2019

Regarding non-dev contributions, this section from the debugger docs has some great stuff we can borrow

One goal we have in the Debugger team is to help the Debugger community (around GitHub) transit to m-c world. David wrote a nice doc to help them

There are several resources related to documentation update:

  • Bug 1535023 - Document setup process for contributors moving from GitHub
  • DevTools Documentation Update Feedback from contributors (doc)
  • Getting started on firefox-dev.tools
  • Contributing to Mozilla Central with git (doc, from David for Debugger community)

I collected all resources in this doc

The feedback from contributors is mostly talking about the following pages:

And I agree that improving the home page would be nice step forward:

Honza

@violasong

This comment has been minimized.

Copy link
Member Author

@violasong violasong commented Jul 17, 2019

@nchevobbe, that sounds great! The single document you're describing makes me think "Quickstart Guide" :). We could make that the first page of the docs, as a one-stop shop for beginners, and the rest of the docs could remain unchanged for advanced folks. (This seems easiest for an MVP, compared to overhauling everything.) It could potentially have the post-build exercise at the end. Would you be able to take the lead on this part of the project? (Hopefully it wouldn't be just you, and you could delegate some sections to other DevToolers :D.) I'm happy to help with copyediting and other feedback.

I can take the lead on the homepage/Introduction changes, and will make a rough proposal/wireframes for that soon.

@janodvarko Great to see so much info already available! That Outreachy feedback doc is an amazing user research artifact. I'll take some time to read it over.

Regarding the debugger switch to mc docs, sounds like that could be considered a separate project for now? @darkwing, if you have thoughts on how that work can feed into the home page or quickstart guide, let me know!

@violasong violasong moved this from Backlog to Today in Victoria's Tasks Jul 17, 2019
@violasong

This comment has been minimized.

Copy link
Member Author

@violasong violasong commented Jul 17, 2019

@nchevobbe Or, maybe @sole would want to take the lead on a Quickstart Guide (if she thinks it's a good idea in general) since she wrote (all/most of?) the docs in the first place :D? Either way, I just think someone who isn't me should own this part of our MVP :)

I found this outreachy applicant's mc/phabricator guide in the feedback doc that looks like something we could draw from.

@nchevobbe

This comment has been minimized.

Copy link
Member

@nchevobbe nchevobbe commented Jul 18, 2019

I'd love to but I don't think I can commit to anything at the moment as I've plenty of things on my place. I may try something, but can't promise anything.

One thought I had too is that maybe we could localize this doc?

@violasong

This comment has been minimized.

Copy link
Member Author

@violasong violasong commented Jul 18, 2019

Totally understandable! Maybe the guide can be divided into more manageable chunks that contributors could take on, and you/others can just help by providing feedback.

Localization would be be a nice thing to look into after this MVP is landed.

@violasong

This comment has been minimized.

Copy link
Member Author

@violasong violasong commented Jul 21, 2019

Next steps: I'm going to talk to Sole about this some more, and start working on patches for the home page and the introductory sections of the doc. No action needed from others for now.

(@nchevobbe: As a first step, I think I can actually take the lead on creating some initial patches to the existing docs based on all the feedback I've seen here - I'll let you/everyone know if I need help with something :))

@violasong violasong moved this from Today to This Week in Victoria's Tasks Jul 24, 2019
@violasong violasong moved this from Next to Current in Victoria's Tasks Dec 26, 2019
@sylvestre

This comment has been minimized.

Copy link

@sylvestre sylvestre commented Dec 27, 2019

@violasong

This comment has been minimized.

Copy link
Member Author

@violasong violasong commented Dec 27, 2019

Thank you @sylvestre! I just realized the DevTools docs are actually in this website. If I make changes to these pages will they be reflected here?

@sylvestre

This comment has been minimized.

@violasong

This comment has been minimized.

Copy link
Member Author

@violasong violasong commented Dec 27, 2019

I see - this is great, thanks!

@violasong

This comment has been minimized.

Copy link
Member Author

@violasong violasong commented Dec 27, 2019

New firefox-dev.tools homepage content is underway in this doc!

Here is some of the ongoing design rationale, cross-posted from DevTools slack:

Big banner:

We'll want to change this up later to look more like a custom website, but for now let's think about the text. Title: Good. Subtitle: "Docs and Guides" is a little wrong since we don't have guides here. What would be better?

Body content:

The first two sentences are pretty straightforward, but could be re-written to be more welcoming.

Documentation section:

"End user guides" - this could be rewritten to be more clear. Also, do we want this here, or perhaps in a later section?
"Developer Documentation" - this link is our biggest "call to action!" It's got a huge amount of info for contributing to DevTools. But it doesn't look or sound like that right now.

News and Demos:

This section isn't really about joining the project. They're both blog categories that aren't updated very often (especially the Nightly blog link). Good overview of the lastest, but maybe should be de-emphasized

Getting in touch:

This section needs some updating and separating out of info. The long bulleted list is a bit daunting. The most important link here is the "List of open bugs" (for inspiring those who may be considering getting started), though that's also in the docs.

The Slack link is also really important, as this is the main place to get help when getting started, and it also acts like a community hangout for us.

Filing bugs in Bugzilla is an important type of contribution that we want to encourage. Maybe that could be a part of a new "Ways to help" section.

Twitter is our most direct and up-to-date news channel, and the easiest way to to get and respond to feedback, so maybe we can say that somehow.

Processes:
The PR info is probably better suited to the docs. The part about RFCs is outdated.
"People and modules" could be more clear. Right now it has a lot of slack (and IRC?) usernames shown out of context. If you have a question about the code, it's probably better to find a slack channel to ask in. The system of module owners is more like a form of governance that may have more internal significance. https://wiki.mozilla.org/Modules (edited)

Now that I've reviewed the existing site, I want to get more inspiration for what a community contributor site could be. I can look at other types of open source contribution sites to see what they do well or not so well. Here's a selection of Mozilla sites, other browsers' sites, and popular open source sites.

Some takeaways:

  • It's nice to see a friendly message up top
  • I like having a list of ways to help near the top, which includes both code and non-code methods, like giving feedback, UX, documentation, and testing prerelease software.
  • Ways to stay in touch are usually in a different section farther down, or in a separate page
  • Clear direction on how to get started, often with the text "Get Started"
  • Mention the tech involved (HTML/CSS/JS), especially because that may make the project seem more accessible
  • TensorFlow has a nice overview about their code of conduct that emphasizes their community values
  • Debugger links to a website that explains how to contribute to open source general
  • Codetribute website has a nice intro about the size and scope of the DevTools team at Mozilla and community of volunteers. They also have a short overview of how to get started on a new issue.
  • In the titles, there's a big mix of wording - first-person vs second-person, questions vs descriptive, informal vs formal
@violasong

This comment has been minimized.

Copy link
Member Author

@violasong violasong commented Dec 31, 2019

First round of changes to the website are live! https://firefox-dev.tools/

I created a new "How to Contribute" section, followed by "Stay Updated" and "About DevTools" sections. Screenshots: Before / After

I also made an initial batch of changes to the MDN page (mainly the intro) https://developer.mozilla.org/en-US/docs/Tools

@violasong

This comment has been minimized.

Copy link
Member Author

@violasong violasong commented Dec 31, 2019

First round of changes to the documentation is now underway!

Filed a PR for the build page: mozilla/gecko-dev#506

Will also be working on the Intro page.

moz-v2v-gh pushed a commit to mozilla/gecko-dev that referenced this issue Jan 24, 2020
gecko-dev-updater pushed a commit to marco-c/gecko-dev-comments-removed that referenced this issue Jan 28, 2020
firefox-devtools/ux#70

Differential Revision: https://phabricator.services.mozilla.com/D58878

UltraBlame original commit: 1d0f06d1271bbb820c798263be01b618babea628
gecko-dev-updater pushed a commit to marco-c/gecko-dev-wordified that referenced this issue Jan 28, 2020
firefox-devtools/ux#70

Differential Revision: https://phabricator.services.mozilla.com/D58878

UltraBlame original commit: 1d0f06d1271bbb820c798263be01b618babea628
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
Victoria's Tasks
  
Current
6 participants
You can’t perform that action at this time.