Join GitHub today
GitHub is home to over 40 million developers working together to host and review code, manage projects, and build software together.
Sign upBetter onboarding for new contributors #70
Comments
This comment has been minimized.
This comment has been minimized.
|
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 comment has been minimized.
This comment has been minimized.
|
I don't have a complete vision, just a few notes:
|
This comment has been minimized.
This comment has been minimized.
|
Thanks both for the ideas!
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.
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.
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.
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.
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. |
This comment has been minimized.
This comment has been minimized.
|
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.
|
This comment has been minimized.
This comment has been minimized.
|
There could also be a landing page-like section on the homepage that shows a images of new features, at least for the following: |
This comment has been minimized.
This comment has been minimized.
|
When outreachy started, these were the main issues people struggled with:
The ideas we should play with are:
|
This comment has been minimized.
This comment has been minimized.
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:
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 |
This comment has been minimized.
This comment has been minimized.
|
@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! |
This comment has been minimized.
This comment has been minimized.
|
@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. |
This comment has been minimized.
This comment has been minimized.
|
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? |
This comment has been minimized.
This comment has been minimized.
|
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. |
This comment has been minimized.
This comment has been minimized.
|
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 :)) |
This comment has been minimized.
This comment has been minimized.
|
we have now a doc for Firefox new contributor: |
This comment has been minimized.
This comment has been minimized.
|
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? |
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
|
I see - this is great, thanks! |
This comment has been minimized.
This comment has been minimized.
|
New firefox-dev.tools homepage content is underway in this doc! Here is some of the ongoing design rationale, cross-posted from DevTools slack:
|
This comment has been minimized.
This comment has been minimized.
|
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 |
This comment has been minimized.
This comment has been minimized.
|
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. |
firefox-devtools/ux#70 Differential Revision: https://phabricator.services.mozilla.com/D58878
firefox-devtools/ux#70 Differential Revision: https://phabricator.services.mozilla.com/D58878 --HG-- extra : moz-landing-system : lando
firefox-devtools/ux#70 Differential Revision: https://phabricator.services.mozilla.com/D58878 UltraBlame original commit: 1d0f06d1271bbb820c798263be01b618babea628
firefox-devtools/ux#70 Differential Revision: https://phabricator.services.mozilla.com/D58878 UltraBlame original commit: 1d0f06d1271bbb820c798263be01b618babea628

Update (December 31): Join me on Slack to follow along and help with the UX process!
Checklist: firefox-dev.tools
Checklist: Contributor Documentation
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 :).