I've been looking through the developer tools documentation on MDN, and started to make a sort of quick assessment of the current status of it, and a sort of plan for what I should work on next.
It's quite rough, and more than possible that I'm missing lots of important stuff, but I'd love to get some feedback on it, and/or some answers to some of the questions.
These are a few things I noticed from looking through the current docs on MDN.
-
Developer tools landing page: it looks to me like the Tools landing page is the nearest thing to a developer tools home on MDN. But it has a lot of links that seem quite old, some of which are perhaps not very useful and some which we might want to de-emphasise in favour of the newer tools. I think we should either refocus it much more closely on the newer developer tools (my preference) or create a new page focused on the newer developer tools. We should also add more context about the developer tools: what they are, what they do, and why you should care.
-
Missing/WIP pages: there's not much on the Firefox OS Simulator, and I could not find anything on MDN about the Toolbox or the remote debugging protocol (although there's lots of WIP stuff in the wiki). The DevTools API is not linked from the main Tools page and has a big scary warning.
-
Status of existing pages: Page Inspector, Scratchpad, and so on. These generally seem pretty current, but need some updates especially around user interfaces, and could definitely use some more examples.
-
for the Tools landing page, is there anything there we should just remove? Is there anything there we should explicitly de-emphasize in favour of the new stuff (e.g. DOM Inspector?)?
-
are there any other big pieces that are missing, apart from the ones I've listed above?
-
what's the current status and future plans for the remote debugging protocol and DevTools API? Who is the audience for it? Primarily internal, or can web developers/add-on developers profitably use it?
-
is there anything specific on extensibility/dev tools as add-ons, that we should plan docs for?
This is my initial idea about what I should so, and the order I should do it in:
-
Documentation for the simulator: work out what's needed here and add the most important stuff.
-
A better landing page: work out what we want to promote/un-promote there and add context about developer tools.
-
Documentation for the toolbox to tie Page Inspector, Style Editor, Web Console &c together
-
Work out how to present devtools extensibility: how to extend the devtools for yourself, and how to find and use devtools that other people have developed.
-
More examples, for everything, and examples that won't rot.
-
Some standalone documentation for remotability, separate from the specific tools that support it.
-
Devtools API documentation, if it's intended for, and ready for use by, more than internal customers
-
Try to figure out a way to document the devtools in the context of a developer workflow. The current docs don't always do a great job of showing how a developer can use the tools together to solve a specific problem. Walkthrough tutorials? People always talk about videos when I mention this, but I hate watching screencasts, because I can't control the rate at which information is presented to me, and it's impossible to search. Is that just me? I had a suggestion that we could use Popcorn to make something that you can play like a video but is browsable too, which might work.
-
Work out how to present the devtools as something that's not necessarily tied to Firefox (the browser), but as its own product that could be used to debug things that support the protocol (including FxOS devices, naturally). I guess that the toolbox and remote debugging documentation could be a start with that.