search

firefox-devtools / ux

Firefox DevTools UX Community
Mozilla Public License 2.0
103 stars 21 forks source link

Better onboarding for new contributors #70

Closed violasong closed 4 years ago

violasong commented 5 years ago

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 :).

eduarmreyes commented 5 years ago

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 commented 5 years ago

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

violasong commented 5 years ago

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 commented 5 years ago

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 commented 5 years ago

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 commented 5 years ago

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:

janodvarko commented 5 years ago

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:

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 commented 5 years ago

@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 commented 5 years ago

@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 commented 5 years ago

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 commented 5 years ago

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 commented 5 years ago

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 :))

sylvestre commented 4 years ago

we have now a doc for Firefox new contributor: https://firefox-source-docs.mozilla.org/tools/docs/contribute/how_to_contribute_firefox.html

violasong commented 4 years ago

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 commented 4 years ago

@violasong yeah :) See https://bugzilla.mozilla.org/show_bug.cgi?id=1599080

violasong commented 4 years ago

I see - this is great, thanks!

violasong commented 4 years ago

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:

violasong commented 4 years ago

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 commented 4 years ago

First round of changes to the documentation is now underway!

Filed a PR for the build page: https://github.com/mozilla/gecko-dev/pull/506

Will also be working on the Intro page.

violasong commented 4 years ago

Changes to main Firefox contributor docs underway! https://bugzilla.mozilla.org/show_bug.cgi?id=1619012

As well as a DevTools beginners guide that tries not to be redundant with the above https://docs.google.com/document/d/1Amby0IYXaOIhbjdL39a2bO0leEiPM2xuO7W7uxpXi9s/edit#

violasong commented 4 years ago

Landed new beginners guide! https://firefox-source-docs.mozilla.org/devtools/getting-started/README.html

Remaining tasks: Clean up doc index https://bugzilla.mozilla.org/show_bug.cgi?id=1628516 Update links to docs https://bugzilla.mozilla.org/show_bug.cgi?id=1628599

janodvarko commented 4 years ago

Thanks @violasong!

I'll be looking at the other two.

Honza

sylvestre commented 4 years ago

Landed new beginners guide! https://firefox-source-docs.mozilla.org/devtools/getting-started/README.html

many many thanks for not duplicating the other doc :) :+1:

violasong commented 4 years ago

Thanks Honza and Sylvestre :)

Since most of the work is done, I'm going to close this issue. I created a new one for this remaining task: Improve design for community site (firefox-dev.tools)