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.

Will, what do you think?

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.

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?

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?

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.

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

Pointer to Github pull-request

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

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