search

captainbrosset / devtools-tips

A collection of useful cross-browser DevTools tips
https://devtoolstips.org
312 stars 33 forks source link

New "Understanding DevTools" guide #105

Closed captainbrosset closed 6 months ago

captainbrosset commented 7 months ago

A new, longer, guide that explains DevTools for people who haven't used it yet (or who have used it, but may not yet fully understand how it works).

This is the first in a series of guides I hope that we can write on the site.

The PR comes with a bunch of build and CSS changes to accommodate for these guides.

This PR isn't ready yet, I still need to figure out where, in the UI, would guide go. Probably on the home page and in the sidebar. But this remains to be done.

Preview of the new guide's content: https://github.com/captainbrosset/devtools-tips/blob/guides/src/guides/en/understand-devtools/index.md

captainbrosset commented 7 months ago

@pankajparashar, as a frequent contributor to the site, I would love your point of view on this guide. If you have time of course. I totally understand if you don't. Here's the preview: https://github.com/captainbrosset/devtools-tips/blob/guides/src/guides/en/understand-devtools/index.md Feel free to leave comments on this PR.

@Kilian you too, in case you have time, and knowing that this doesn't cover Polypane, since it's quite different from the other built-in devtools :)

pankajparashar commented 7 months ago

@captainbrosset I think it's a fantastic idea! The official docs are sometimes a bit too overwhelming for not only the beginners but also for the seasoned campaigners while trying to navigate through the docs.

  1. I liked the idea of using skeleton illustrations to explain the increasingly complex UI of DevTools. Perhaps this could be a theme throughout the guide, where we explain features through visual representation. Of course it will take a lot of work to produce such a guide. I always dreamed of an "interactive" guide but not sure if that is even possible.

  2. We definitely need some standard nomenclatures to refer to different parts of the DevTools UI. Most of which you have already covered here. It's easy for people to get confused between panel vs pane, tab vs drawer etc., I know that Edge docs tends to refer "Network", "Console" as tools whereas other browser docs refer them as tabs (or panels).

  3. I particularly admire your writing style which is very personal, as if you are speaking directly with the reader and is a great way to connect with the reader. I'm interested in seeing how the guide will handle cross-browser differences in the DevTools UI. Similar features are named differently or represented differently across different browsers.

  4. Would be good to understand how to strike a balance between a general guide vs a detailed documentation of a feature? At what point the beginner stops reading the guide and becomes comfortable enough to read the official docs? I imagine the end goal is not to replace the docs but to provide an entry point to the amateur web developers to become comfortable enough with the DevTools UI.

I cannot imagine anyone more qualified than you for writing this guide. I'm sure I'll have more thoughts in the coming days, as I re-read the guide and gather my thoughts. Great work and looking forward for updates on this thread!

captainbrosset commented 6 months ago

Merging this PR to avoid having to maintain the system-level changes for too long, but without actually making the new guide visible on the site. It'll be built as part of the site, but just not accessible through navigation.

This way, I can open a new PR to finalize just the guide and make it available on the site.