Confirmed users
228
edits
MDN/Projects/Completed/GitHub Integration: Difference between revisions
MDN/Projects/Completed/GitHub Integration (view source)
Revision as of 16:20, 2 December 2013
, 2 December 2013no edit summary
No edit summary |
|||
| Line 111: | Line 111: | ||
I think it's an open question whether we accomplish this by extending readthedocs.org or whether we roll our own thing. I'd much prefer us to use readthedocs.org, and to give any improvements back, but having looked a bit at readthedocs.org, it seems to be very heavily dependent on the docs using Sphinx/reStructuredText - so if it's important to us to support other formats (which it probably is) and other ways of generating a docset from a pile of source files, then it might be a big change. | I think it's an open question whether we accomplish this by extending readthedocs.org or whether we roll our own thing. I'd much prefer us to use readthedocs.org, and to give any improvements back, but having looked a bit at readthedocs.org, it seems to be very heavily dependent on the docs using Sphinx/reStructuredText - so if it's important to us to support other formats (which it probably is) and other ways of generating a docset from a pile of source files, then it might be a big change. | ||
== Potential test subject: the Emscripten Wiki == | |||
Emscripten, Mozilla's LLVM bytecode -> JavaScript compiler, currently has its most complete source of documentation on the Emscripten Wiki located at https://github.com/kripken/emscripten/wiki. This project already has a dedicated community of contributors, although the site currently doesn't look very professional and could do with some editing and structural improvements. | |||
The MDN team and Emscripten engineers would like to improve on this situation. The former group would obviously prefer the content to be just ported over to an MDN zone, for the MDN editors to have their wicked way with. The latter group have some reservations: | |||
* The Wiki on Github already has a dedicated community, who might get confused if it is suddenly uprooted and moved. | |||
* A lot of engineers prefer to write markdown and host on Github, rather than using a WYSIWYG tool like MDN. | |||
* They want Emscripten to stand up on its own as an independent project, and not be seen as Mozilla biased, which is a potential danger of putting it up on MDN. | |||
* We could put some content up on a dedicated Emscripten site, and then link to MDN for other content, but this might be a bit of a weird experience for users to go to the main Emscripten site, and then be put on a different site. | |||
Whatever happens, we need to put some content up on MDN anyway about Emscripten (which would probably be basic intro/hello world, writen in a different style so as not to duplicate the main site too much.) But it would be really amazing to be able to transclude some of the content from the Emscripten Wiki directly onto MDN, cutting out any needless duplication of content, and allowing the Emscripten contributors to write the docs their way and keep their separate site. | |||
We have already created a sample Emscripten zone at https://developer.mozilla.org/en-US/docs/Emscripten, to add test content to as we discuss this project, and the best way to proceed. | |||
==References== | ==References== | ||
https://etherpad.mozilla.org/github-mdn | https://etherpad.mozilla.org/github-mdn | ||