Closed Bug 1257322 Opened 8 years ago Closed 8 years ago

Flesh out initial devtools/doc structure and add SUMMARY.md

Categories

(DevTools :: General, defect)

defect
Not set
normal

Tracking

(firefox48 fixed)

RESOLVED FIXED
Firefox 48
Tracking Status
firefox48 --- fixed

People

(Reporter: jlong, Assigned: jlong)

Details

Attachments

(1 file, 1 obsolete file)

SUMMARY.md is required to tell gitbook the structure to build out. Once we have this we can build our docs into a site and host it on github or somewhere.

This initial structure is not set in stone by any means. It's just something to get us going. We can restructure it as much as we want, but I really want to start writing React & Redux docs/guidelines.
Attached patch 1257322.patch (obsolete) — Splinter Review
I'm going to change this patch a bit before landing, but here's current progress
Assignee: nobody → jlong
Attached patch 1257322.patchSplinter Review
Assigning to you, thought you might be interested :) feel free to re-assign
Attachment #8731426 - Attachment is obsolete: true
Attachment #8732307 - Flags: review?(pbrosset)
Comment on attachment 8732307 [details] [diff] [review]
1257322.patch

Review of attachment 8732307 [details] [diff] [review]:
-----------------------------------------------------------------

Quick R+ for this. I haven't reviewed the content of the react/redux doc files because it's not my place to do so. This is a good start, and I like the idea of having our in-tree doc more easily accessible. So let's just ship this and build on top.
Attachment #8732307 - Flags: review?(pbrosset) → review+
Actually, thinking about it more, I'm not sure we should have the coding style and contribution docs in this patch. I know they are just basically links to our wikis, but still, I think there is value in keeping this purely about technical architecture docs (react, debugger protocol, front-end architecture, etc.).
At least until we figure out what we want to do with these 3 different docs:
- https://wiki.mozilla.org/DevTools/Hacking
  => Our official docs
- https://developer.mozilla.org/en-US/docs/Tools/Contributing/Contribute_on_nightly
  => A new way to contribute using git and the DevTools Reload addon
- https://groups.google.com/forum/#!topic/mozilla.dev.developer-tools/BLgCfdVnBjI
  => A new proposal to have contributor docs on http://firefox-dev.tools

The final vision, I think, is to have one agreed way to contribute (most probably using git and potentially with the Reload addon when possible), then document this nicely on http://firefox-dev.tools
and make sure the wiki and mdn pages go away.
When that happens, we could have a sub-section in http://firefox-dev.tools that contains internal tech docs which would basically be the git-book you're working on.
So it makes sense then not to have any page of this book being about contributing, since we'll have that somewhere else already.

Of course we need someone to champion this and actually make it happen (I think Gabriel wants to do this). And there's a lot of sub-docs on https://wiki.mozilla.org/DevTools/Hacking which would need to be moved too.
(In reply to Patrick Brosset [:pbro] from comment #4)
> Actually, thinking about it more, I'm not sure we should have the coding
> style and contribution docs in this patch. I know they are just basically
> links to our wikis, but still, I think there is value in keeping this purely
> about technical architecture docs (react, debugger protocol, front-end
> architecture, etc.).

I was thinking of moving everything in here, but after thinking a bit more, I agree. It's too important to be able to quickly change the "getting started" docs and those changes are frequent small tweaks. It would be annoying to commit to the tree for all of that.

I had already removed the "getting started" page and I just removed the "coding style" section. I kept a very short section in the main intro page that link to the other pages, as I still think we should reference them. But having them as separate sections isn't good.

To me, this isn't *purely* technical docs. You'll notice that the react and redux sections explain a lot about the concepts behind them. I like to this of these as friendly technical docs; they don't just document what's there, they take time to explain abstract concepts as well. Part of that friendliness is to at least mention the getting started/etc pages in the README.md.

I see these as docs for everyone but beginner contributors. Another good example is hot reloading: I'm not sure we should mention it in "getting started" because it's an advanced feature. It doesn't work everywhere, so it could just confuse beginners more. But it'd be great to have a "Advanced Tips" section in these docs or something that explain how to enable hot reloading. Other tips are how to profile react, how to debug redux, etc. I'd like to see all of that as part of these docs.

> At least until we figure out what we want to do with these 3 different docs:
> - https://wiki.mozilla.org/DevTools/Hacking
>   => Our official docs
> -
> https://developer.mozilla.org/en-US/docs/Tools/Contributing/
> Contribute_on_nightly
>   => A new way to contribute using git and the DevTools Reload addon
> -
> https://groups.google.com/forum/#!topic/mozilla.dev.developer-tools/
> BLgCfdVnBjI
>   => A new proposal to have contributor docs on http://firefox-dev.tools
> 
> The final vision, I think, is to have one agreed way to contribute (most
> probably using git and potentially with the Reload addon when possible),
> then document this nicely on http://firefox-dev.tools
> and make sure the wiki and mdn pages go away.
> When that happens, we could have a sub-section in http://firefox-dev.tools
> that contains internal tech docs which would basically be the git-book
> you're working on.
> So it makes sense then not to have any page of this book being about
> contributing, since we'll have that somewhere else already.

I don't agree that we should combine these projects. I think they are separate: that one is for beginner contributors, and these docs are for everyone else. Anyone who consistently contributes is going to want to download/compile firefox, enable hot reloading, etc, all the stuff that we do and should not be the focus of beginner docs.

I think having 2 separate projects relieves the tension of "who are we focusing on"? We can do both. firefox-dev.tools even has that big app for searching for bugs, which is great for beginner contributors but not really needed for anyone more involved (I think?).

There's also technical easiness: I'm making a stupid simple service that checks out firefox and force pushes the latest docs to the github repo so it's always up-to-date. I can't do that if there's anything else in the repo that is actually using the repo to track changes. I also want to work with Helen on some snazzy designs (at least a logo and some colors) and I don't want to have to coordinate designs with the bug finder tool.

Anyway, we'll see how it evolves, it might make sense in the future but for now I don't think it makes much sense. Definitely agree that any docs about getting set up should not be here though.
Gonna land this, several things we still need to do (a bunch of links are broken) but I'd rather iterate than stall.
https://hg.mozilla.org/mozilla-central/rev/9e9f949b36c8
Status: NEW → RESOLVED
Closed: 8 years ago
Resolution: --- → FIXED
Target Milestone: --- → Firefox 48
Product: Firefox → DevTools
You need to log in before you can comment on or make changes to this bug.