Improve the getting started experience

[jasonLaster]

I spoke with @viswanathamsantosh, @bacharakis, and Lucy Harris earlier and we discussed some of the ways we could improve the getting started process:

Some concrete next steps were:

1. have a dedicated getting started doc that was as focused as possible
2. have an activity for understanding how the debugger works "debugging the debugger"

Here is a branch where i started working on a dedicated getting started doc and activity doc.

Note, that it's lots of rough ideas and needs lots of polish. I'm hoping you guys could help with this.

Also, it's fine to land a better getting started doc and then an activity doc. It doesn't have to be grouped.

@clarkbw, @wldcordeiro, @Garbee I know you have lots of expertise here as well!

[jasonLaster]

Here are my highlevel thoughts on the activity:

1. setup and free form hack
2. style a theme based on an image
3. have the debugger do something cool when adding a breakpoint
4. have the debugger do something cool when pausing

I don't know what 3 and 4 should be :)

Obviously, open to lots of ideas here! Everyone submit cool things

@helenvholmes I think you'd be especially good at this!!!

Also @helenvholmes do you have time to whip up a crazy fast debugger retro theme people could try and implement for funzies...

[jasonLaster]

Here are some thoughts that informed the getting started doc

• focus on the happy path (mac, debugging Firefox). We can have secondary material
• have common questions
• provide screenshots
• provide more space for beginners. Team members can scan it.

[Garbee]

I am going to work on an outline for the initial document today. That way we have something to discuss.

I'll reference the existing stuff with some salt. Then analyze my own understanding of what people should know. Cross-compare and trim out some fat and we should have a good basic outline to work from.

[jasonLaster]

@Garbee, @viswanathamsantosh, @clarkbw just landed #1334, #1331, and #1323 which should really help with the docs

Here are some links

https://github.com/devtools-html/debugger.html/blob/master/CONTRIBUTING.md
https://github.com/devtools-html/debugger.html/blob/master/docs/getting-setup.md
https://github.com/devtools-html/debugger.html/blob/master/docs/local-development.md
https://github.com/devtools-html/debugger.html/blob/master/docs/debugging-the-debugger.md

https://github.com/devtools-html/debugger.html/blob/master/packages/devtools-client-adapters/README.md
https://github.com/devtools-html/debugger.html/blob/master/packages/devtools-local-toolbox/README.md

Hopefully, this will have improved the structure enough where you guys can work your magic and really make it good... I think prior to this work everything was so scattered that it was hard to get your head around it.

[jasonLaster]

@monicau, @jacobjzhang, @akhillb, @svenvNL, @SezginEge, @gavlu, @samuelfullerthomas, @Dalimil we just re-wrote our getting started docs. Do you have any suggestions on how to make them more beginner friendly?

@JasonWeathersby any constructive criticism?

CONTRIBUTING.md
docs/getting-setup.md
docs/local-development.md
docs/debugging-the-debugger.md

packages/devtools-client-adapters/README.md
packages/devtools-local-toolbox/README.md

[Dalimil]

'Getting Started' link in /CONTRIBUTING.md is dead... I guess it should link to getting-setup.md instead...?

[clarkbw]

Oh, I think that's supposed to be https://github.com/devtools-html/debugger.html/blob/master/docs/getting-setup.md

[mayank-gupta]

The file names here are outdated.