Erik Vold [:erikvold] (please needinfo? me) Reporter
	Description • 11 years ago

I cannot think of another project, certainly no Mozilla project which has the documentation, or the code that generates documentation, and the actually project code so closely coupled.

Can anyone think of an example where this is the case?

I think all of the documentation and the documentation generation code, should be separated out of sdk repo, and moved to a separate repo.

If we want to generate documentation from code comments, then that generation code should still be separated.

	Jeff Griffiths (:canuckistani) (:⚡︎)
	Comment 1 • 11 years ago

Will, what do you think?

	Erik Vold [:erikvold] (please needinfo? me) Reporter
	Comment 2 • 11 years ago

Will, Jeff and I talked about this on Wednesday and we think that moving the docs to MDN is the best approach.  Jetpack used to be a product, whereas now it is a set of APIs in the browser, so shipping docs with the product no longer makes any sense.

	Will Bamberg [:wbamberg] Assignee
	Comment 3 • 11 years ago

well...I think having the docs "on MDN" (hosted on developer.mozilla.org, and presented to be consistent with the other stuff on there) is the right thing to do.

I think, personally, that having them in source control, close to the code, with the opportunity for some editorial control, and generated using some sort of markup (for the API reference docs) makes for better (=more consistently structured, more correct, more well-organized) content than having them in the Wiki. But I'm really tired of arguing documentation-system philosophy (wikis are the best! wikis are the worst! in-source docs are the best! in-source docs are the worst! Markdown is the best! Markdown is the worst!). Putting them in the wiki is the conventional thing to do, so let's do that.

More pragmatically, I think they will work better in the Wiki once the redesign (https://wiki.mozilla.org/MDN/Development/Redesign) is done, mostly because that will permit us to have something like a sidebar where we can link to API reference pages.

What's the timeline on this work, and what's driving that timeline?

	Jeff Griffiths (:canuckistani) (:⚡︎)
	Comment 4 • 11 years ago

We should wait to do this until the docs have been moved, as per Will's comment. Will, can you have that bug block this bug when it is filed?

	Erik Vold [:erikvold] (please needinfo? me) Reporter
	Comment 7 • 11 years ago

Comment on attachment 8358887 [details]
Link to Github pull-request: https://github.com/mozilla/addon-sdk/pull/1342

Trying to take a review off of Irakli's plate.

	[github robot]
	Comment 8 • 11 years ago

Commits pushed to master at https://github.com/mozilla/addon-sdk

https://github.com/mozilla/addon-sdk/commit/3a7bd03c4eba6798f35a4b1ec3bfb8ee6ef9df98
Bug 903032 removing docs related python

https://github.com/mozilla/addon-sdk/commit/e647c4e9d2aeb4e5612a0d98c44e701260fa0e32
Merge pull request #1342 from erikvold/remove-doc-py

Bug 903032 removing docs related python r=@Mossop

	Erik Vold [:erikvold] (please needinfo? me) Reporter
	Comment 9 • 11 years ago

Pointer to Github pull-request

	Jordan Santell [:jsantell] [@jsantell]
	Comment 10 • 11 years ago

Comment on attachment 8364147 [details]
Pointer to Github pull request: https://github.com/mozilla/addon-sdk/pull/1360

Looks good, but I'm not super familiar with the cuddlefish test code. If cuddlefish tests are still working, looks good

	[github robot]
	Comment 11 • 11 years ago

Commits pushed to master at https://github.com/mozilla/addon-sdk

https://github.com/mozilla/addon-sdk/commit/79232c6bd394f822bb2b38873c03b8db04a33830
Bug 903032 removing code for testing docs related python

https://github.com/mozilla/addon-sdk/commit/809a77a2f3d79270a0ebbb3ea9ef735c58ce6cdb
Merge pull request #1360 from erikvold/903032p3

Bug 903032 removing code for testing docs which no longer exist in this repo r=@jsantell