Cleaning up DevTools docs

[Patrick Brosset]

Sole did a talk last week in Paris about the state of our docs [1].
tl;dr; they're confusing, scattered all over the place, duplicated, and
sometimes wrong.

The good news is there are actually some very concrete things we can do
today to help.

Technical docs (APIs, architecture, ...) make more sense near the source
code. We have a bunch of them already in /devtools/docs/ and
/devtools/server/docs/
Here are 3 things we can do:

- Some technical docs are on the wiki still. We should move them.

I have made a shared doc [2] that lists all the DevTools wiki pages, and
annotated some that should be moved to /devtools/docs/.
If you want to help with this, just put your name in the shared doc, file a
bug, and just move the page. I'll happily accept patches and review them
quickly.

- There are some unfinished technical docs in /devtools/docs/. Let's fill
the gap!

For example /devtools/docs/react-tips.md has a TODO at the end.
/devtools/docs/debugger-panel.md should probably point to the docs on
https://github.com/devtools-html/debugger.html
And there are more.

- Finally, please be aware of when you explain things to people.

It usually is a sign that that thing should be documented somewhere, so the
knowledge doesn't only stay between you two.
If the thing you just explained is technical, then please file a bug for
creating the doc for it in the source code.

Let's make our docs awesome so everyone can learn about DevTools easily!
Patrick

[1]
https://docs.google.com/document/d/1XvCBYg4YKyrZLg2CfHkbzZg7P85MLg6R0WdjFIoQqY0/edit#heading=h.g95tu2im696k
[2]
https://docs.google.com/document/d/1XrrvgSZka1uEeYynZRf99FI0ejiCIz_rGyuKHrFx8rI/edit#heading=h.p3ivx4c6ekx9

[Michael (work)]

Have we considered generating API docs from JSDoc comments? It is a
great way to ensure that APIs stay up-to-date, especially if we tag
public facing methods and generate according to that.

Of course, other types of docs should live alongside the source code in
the tree.

> _______________________________________________
> dev-developer-tools mailing list
> dev-devel...@lists.mozilla.org
> https://lists.mozilla.org/listinfo/dev-developer-tools